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
2020-03-31 18:54:46 +00:00
**[Try it out](https://video.etherpad.com)**
2013-04-04 00:22:46 +00:00
2021-02-20 13:22:23 +00:00
# Project Status
### Code Quality
[](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)
### Testing
[](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)
[](https://github.com/ether/etherpad-lite/actions/workflows/frontend-admin-tests.yml) [](https://github.com/ether/etherpad-lite/actions/workflows/frontend-tests.yml)
### Engagement
< a href = "https://hub.docker.com/r/etherpad/etherpad" > < img alt = "Docker Pulls" src = "https://img.shields.io/docker/pulls/etherpad/etherpad" > < / a >
  
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
2019-10-19 22:40:18 +00:00
This package runs on any Windows machine, but for development purposes, please do a manual install.
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 )
