2019-10-19 22:40:18 +00:00
# A real-time collaborative editor for the web
2020-07-15 16:35:17 +00:00
2020-04-19 15:27:33 +00:00
2011-08-21 16:23:04 +00:00
2011-04-07 14:17:40 +00:00
# About
2020-11-09 08:32:18 +00:00
Etherpad is a real-time collaborative editor [scalable to thousands of simultaneous real time users ](http://scale.etherpad.org/ ). It provides [full data export ](https://github.com/ether/etherpad-lite/wiki/Understanding-Etherpad's-Full-Data-Export-capabilities ) capabilities, and runs on _your_ server, under _your_ control.
2018-04-03 18:55:55 +00:00
2021-02-23 07:24:39 +00:00
# Try it out
Etherpad is extremely flexible providing you the means to modify it to solve whatever problem your community has. We provide some demo instances for you try different experiences available within Etherpad. Pad content is automatically removed after 24 hours.
* [Rich Editing ](https://rich.etherpad.com ) - A full rich text WYSIWYG editor.
* [Minimalist editor ](https://minimalist.etherpad.com ) - A minimalist editor that can be embedded within your tool.
* [Dark Mode ](https://dark.etherpad.com ) - Theme settings to have Etherpad start in dark mode, ideal for using Etherpad at night or for long durations.
* [Images ](https://image.etherpad.com ) - Plugins to improve provide Image support within a pad.
* [Video Chat ](https://video.etherpad.com ) - Plugins to enable Video and Audio chat in a pad.
* [Collaboration++ ](https://collab.etherpad.com ) - Plugins to improve the really-real time collaboration experience, suitable for busy pads.
* [Document Analysis ](https://analysis.etherpad.com ) - Plugins to improve author and document analysis during and post creation.
2013-04-04 00:22:46 +00:00
2021-02-20 13:22:23 +00:00
# Project Status
### Code Quality
2021-02-22 09:28:37 +00:00
[](https://github.com/ether/etherpad-lite/actions/workflows/codeql-analysis.yml) [](https://lgtm.com/projects/g/ether/etherpad-lite/alerts/) [](https://lgtm.com/projects/g/ether/etherpad-lite/context:javascript) [](https://github.com/ether/etherpad-lite/actions/workflows/lint-package-lock.yml)
2021-02-20 13:22:23 +00:00
### Testing
2021-02-22 09:28:37 +00:00
[](https://github.com/ether/etherpad-lite/actions/workflows/backend-tests.yml) [](https://github.com/ether/etherpad-lite/actions/workflows/load-test.yml) [](https://github.com/ether/etherpad-lite/actions/workflows/rate-limit.yml) [](https://github.com/ether/etherpad-lite/actions/workflows/windows-zip.yml) [](https://github.com/ether/etherpad-lite/actions/workflows/dockerfile.yml)
2021-02-25 10:44:00 +00:00
[](https://github.com/ether/etherpad-lite/actions/workflows/frontend-admin-tests.yml) [](https://github.com/ether/etherpad-lite/actions/workflows/frontend-tests.yml) [](https://github.com/ether/etherpad-lite/actions/workflows/windows-installer.yml)
2021-02-20 13:22:23 +00:00
### Engagement
2021-02-22 09:37:30 +00:00
< a href = "https://hub.docker.com/r/etherpad/etherpad" >< img alt = "Docker Pulls" src = "https://img.shields.io/docker/pulls/etherpad/etherpad?color=%2344b492" ></ a >    
2021-02-20 13:22:23 +00:00
2018-04-03 11:52:34 +00:00
# Installation
2013-04-04 00:24:09 +00:00
2018-07-26 23:45:06 +00:00
## Requirements
2021-01-19 16:37:12 +00:00
- `nodejs` >= **10.17.0** .
2018-07-26 23:45:06 +00:00
2019-10-19 22:40:18 +00:00
## GNU/Linux and other UNIX-like systems
### Quick install on Debian/Ubuntu
2018-04-03 11:52:34 +00:00
```
2020-12-16 19:50:21 +00:00
curl -sL https://deb.nodesource.com/setup_14.x | sudo -E bash -
2019-10-19 22:40:18 +00:00
sudo apt install -y nodejs
2021-02-04 23:43:27 +00:00
git clone --branch master https://github.com/ether/etherpad-lite.git & &
cd etherpad-lite & &
src/bin/run.sh
2018-04-03 11:52:34 +00:00
```
2013-04-04 00:24:09 +00:00
2019-10-19 22:40:18 +00:00
### Manual install
2021-01-19 16:37:12 +00:00
You'll need git and [node.js ](https://nodejs.org ) installed (minimum required Node version: **10.17.0** ).
2012-09-10 12:44:06 +00:00
2018-04-03 11:52:34 +00:00
**As any user (we recommend creating a separate user called etherpad):**
2013-10-12 18:38:51 +00:00
2019-01-25 22:05:05 +00:00
1. Move to a folder where you want to install Etherpad. Clone the git repository: `git clone --branch master git://github.com/ether/etherpad-lite.git`
2018-07-26 22:42:13 +00:00
2. Change into the new directory containing the cloned source code: `cd etherpad-lite`
2021-02-04 23:43:27 +00:00
3. run `src/bin/run.sh` and open < http: // 127 . 0 . 0 . 1:9001 > in your browser.
2012-09-10 12:44:06 +00:00
2021-02-04 23:43:27 +00:00
To update to the latest released version, execute `git pull origin` . The next
start with `src/bin/run.sh` will update the dependencies.
2011-08-12 13:57:24 +00:00
2018-04-03 11:52:34 +00:00
[Next steps ](#next-steps ).
2013-04-01 12:07:38 +00:00
2011-08-21 16:23:04 +00:00
## Windows
2011-08-12 13:57:24 +00:00
2018-07-26 22:42:13 +00:00
### Prebuilt Windows package
2021-02-24 15:51:39 +00:00
This package runs on any Windows machine. You can perform a manual installation via git for development purposes, but as this uses symlinks which performs unreliably on Windows, please stick to the prebuilt package if possible.
2012-09-10 12:44:06 +00:00
2019-04-15 22:54:54 +00:00
1. [Download the latest Windows package ](https://etherpad.org/#download )
2012-09-10 12:44:06 +00:00
2. Extract the folder
2019-10-19 22:40:18 +00:00
Run `start.bat` and open < http: // localhost:9001 > in your browser. You like it? [Next steps ](#next-steps ).
2012-09-10 12:44:06 +00:00
2018-12-01 13:15:40 +00:00
### Manually install on Windows
2017-09-14 11:33:27 +00:00
You'll need [node.js ](https://nodejs.org ) and (optionally, though recommended) git.
2012-09-10 12:44:06 +00:00
1. Grab the source, either
2012-11-14 19:05:58 +00:00
- download < https: // github . com / ether / etherpad-lite / zipball / master >
2019-10-19 22:40:18 +00:00
- or `git clone --branch master https://github.com/ether/etherpad-lite.git`
2021-02-04 23:43:27 +00:00
2. With a "Run as administrator" command prompt execute
`src\bin\installOnWindows.bat`
2012-09-10 12:44:06 +00:00
Now, run `start.bat` and open < http: // localhost:9001 > in your browser.
2021-02-04 23:43:27 +00:00
Update to the latest version with `git pull origin` , then run
`src\bin\installOnWindows.bat` , again.
2012-09-10 12:44:06 +00:00
2015-01-20 15:53:52 +00:00
If cloning to a subdirectory within another project, you may need to do the following:
2021-02-16 06:38:04 +00:00
1. Start the server manually (e.g. `node src/node/server.js` )
2015-01-20 15:53:52 +00:00
2. Edit the db `filename` in `settings.json` to the relative directory with the file (e.g. `application/lib/etherpad-lite/var/dirty.db` )
3. Add auto-generated files to the main project `.gitignore`
2019-11-08 22:17:34 +00:00
## Docker container
Find [here ](doc/docker.md ) information on running Etherpad in a container.
2012-09-10 12:44:06 +00:00
# Next Steps
2011-04-07 14:17:40 +00:00
2012-09-10 12:44:06 +00:00
## Tweak the settings
2018-07-26 22:39:51 +00:00
You can modify the settings in `settings.json` .
2021-02-04 23:43:27 +00:00
If you need to handle multiple settings files, you can pass the path to a
settings file to `src/bin/run.sh` using the `-s|--settings` option: this allows
you to run multiple Etherpad instances from the same installation.
2018-07-26 22:39:51 +00:00
Similarly, `--credentials` can be used to give a settings override file, `--apikey` to give a different APIKEY.txt file and `--sessionkey` to give a non-default SESSIONKEY.txt.
2019-03-21 00:37:19 +00:00
**Each configuration parameter can also be set via an environment variable**, using the syntax `"${ENV_VAR}"` or `"${ENV_VAR:default_value}"` . For details, refer to `settings.json.template` .
2019-10-19 22:40:18 +00:00
Once you have access to your `/admin` section settings can be modified through the web browser.
2012-02-21 20:36:05 +00:00
2019-10-19 22:40:18 +00:00
If you are planning to use Etherpad in a production environment, you should use a dedicated database such as `mysql` , since the `dirtyDB` database driver is only for testing and/or development purposes.
2011-11-18 02:49:00 +00:00
2018-08-08 22:17:15 +00:00
## Secure your installation
If you have enabled authentication in `users` section in `settings.json` , it is a good security practice to **store hashes instead of plain text passwords** in that file. This is _especially_ advised if you are running a production installation.
Please install [ep_hash_auth plugin ](https://www.npmjs.com/package/ep_hash_auth ) and configure it.
If you prefer, `ep_hash_auth` also gives you the option of storing the users in a custom directory in the file system, without having to edit `settings.json` and restart Etherpad each time.
2020-04-19 15:27:33 +00:00
## Customize functionalities with plugins
2014-10-28 23:07:02 +00:00
2014-10-29 01:13:05 +00:00
Etherpad is very customizable through plugins. Instructions for installing themes and plugins can be found in [the plugin wiki article ](https://github.com/ether/etherpad-lite/wiki/Available-Plugins ).
2014-10-28 23:07:02 +00:00
2020-07-15 16:35:17 +00:00
## Getting the full features
Run the following command in your Etherpad folder to get all of the features visible in the demo gif:
```
2021-02-16 00:10:55 +00:00
npm install --no-save --legacy-peer-deps ep_headings2 ep_markdown ep_comments_page ep_align ep_font_color ep_webrtc ep_embedded_hyperlinks2
2020-07-15 16:35:17 +00:00
```
2020-04-19 15:27:33 +00:00
## Customize the style with skin variants
Open < http: / / 127 . 0 . 0 . 1:9001 / p / test # skinvariantsbuilder > in your browser and start playing !
2012-09-10 12:44:06 +00:00
## Helpful resources
2018-04-03 11:52:34 +00:00
The [wiki ](https://github.com/ether/etherpad-lite/wiki ) is your one-stop resource for Tutorials and How-to's.
2011-06-02 11:29:09 +00:00
2018-02-08 18:58:27 +00:00
Documentation can be found in `doc/` .
2011-08-04 19:33:39 +00:00
2012-09-10 12:44:06 +00:00
# Development
2011-06-02 11:29:09 +00:00
2012-09-10 12:44:06 +00:00
## Things you should know
2011-06-02 11:29:09 +00:00
2021-02-04 23:43:27 +00:00
You can debug Etherpad using `src/bin/debugRun.sh` .
You can run Etherpad quickly launching `src/bin/fastRun.sh` . It's convenient for
developers and advanced users. Be aware that it will skip the dependencies
update, so remember to run `src/bin/installDeps.sh` after installing a new
dependency or upgrading version.
2020-04-17 16:36:24 +00:00
2012-11-14 19:26:37 +00:00
If you want to find out how Etherpad's `Easysync` works (the library that makes it really realtime), start with this [PDF ](https://github.com/ether/etherpad-lite/raw/master/doc/easysync/easysync-full-description.pdf ) (complex, but worth reading).
2011-08-02 21:15:59 +00:00
2018-04-03 11:52:34 +00:00
## Contributing
2018-04-03 11:57:14 +00:00
Read our [**Developer Guidelines** ](https://github.com/ether/etherpad-lite/blob/master/CONTRIBUTING.md )
2011-08-01 18:24:11 +00:00
2012-09-10 12:44:06 +00:00
# Get in touch
2019-10-19 22:40:18 +00:00
The official channel for contacting the development team is via the [Github issues ](https://github.com/ether/etherpad-lite/issues ).
2011-08-01 18:24:11 +00:00
2020-10-22 15:39:03 +00:00
For **responsible disclosure of vulnerabilities** , please write a mail to the maintainers (a.mux@inwind.it and contact@etherpad.org).
Join the official [Etherpad Discord Channel ](https://discord.com/invite/daEjfhw )
2019-10-19 22:49:46 +00:00
2018-04-03 11:52:34 +00:00
# HTTP API
Etherpad is designed to be easily embeddable and provides a [HTTP API ](https://github.com/ether/etherpad-lite/wiki/HTTP-API )
2018-12-01 13:11:01 +00:00
that allows your web application to manage pads, users and groups. It is recommended to use the [available client implementations ](https://github.com/ether/etherpad-lite/wiki/HTTP-API-client-libraries ) in order to interact with this API.
2018-04-03 11:52:34 +00:00
2020-03-29 18:25:43 +00:00
OpenAPI (previously swagger) definitions for the API are exposed under `/api/openapi.json` .
2018-12-01 13:11:01 +00:00
# jQuery plugin
2018-04-03 11:57:14 +00:00
There is a [jQuery plugin ](https://github.com/ether/etherpad-lite-jquery-plugin ) that helps you to embed Pads into your website.
2018-04-03 11:52:34 +00:00
# Plugin Framework
2020-08-03 11:39:43 +00:00
Etherpad offers a plugin framework, allowing you to easily add your own features. By default your Etherpad is extremely light-weight and it's up to you to customize your experience. Once you have Etherpad installed you should [visit the plugin page ](https://static.etherpad.org/ ) and take control.
2018-04-03 11:52:34 +00:00
# Translations / Localizations (i18n / l10n)
2020-08-02 12:23:26 +00:00
Etherpad comes with translations into all languages thanks to the team at [TranslateWiki ](https://translatewiki.net/ ).
2018-04-03 11:52:34 +00:00
2020-08-03 21:27:45 +00:00
If you require translations in [plugins ](https://static.etherpad.org/ ) please send pull request to each plugin individually.
2018-04-03 11:52:34 +00:00
# FAQ
Visit the ** [FAQ ](https://github.com/ether/etherpad-lite/wiki/FAQ )**.
2011-08-01 18:24:11 +00:00
2012-02-26 14:22:32 +00:00
# License
2012-11-14 19:26:37 +00:00
[Apache License v2 ](http://www.apache.org/licenses/LICENSE-2.0.html )
