2ea8ea1275
Also add symlinks from the old `bin/` and `tests/` locations to avoid
breaking scripts and other tools.
Motivations:
* Scripts and tests no longer have to do dubious things like:
require('ep_etherpad-lite/node_modules/foo')
to access packages installed as dependencies in
`src/package.json`.
* Plugins can access the backend test helper library in a non-hacky
way:
require('ep_etherpad-lite/tests/backend/common')
* We can delete the top-level `package.json` without breaking our
ability to lint the files in `bin/` and `tests/`.
Deleting the top-level `package.json` has downsides: It will cause
`npm` to print warnings whenever plugins are installed, npm will
no longer be able to enforce a plugin's peer dependency on
ep_etherpad-lite, and npm will keep deleting the
`node_modules/ep_etherpad-lite` symlink that points to `../src`.
But there are significant upsides to deleting the top-level
`package.json`: It will drastically speed up plugin installation
because `npm` doesn't have to recursively walk the dependencies in
`src/package.json`. Also, deleting the top-level `package.json`
avoids npm's horrible dependency hoisting behavior (where it moves
stuff from `src/node_modules/` to the top-level `node_modules/`
directory). Dependency hoisting causes numerous mysterious
problems such as silent failures in `npm outdated` and `npm
update`. Dependency hoisting also breaks plugins that do:
require('ep_etherpad-lite/node_modules/foo')
|
||
|---|---|---|
| .github | ||
| doc | ||
| node_modules | ||
| src | ||
| var | ||
| .dockerignore | ||
| .gitignore | ||
| .travis.yml | ||
| CHANGELOG.md | ||
| CONTRIBUTING.md | ||
| Dockerfile | ||
| LICENSE | ||
| Makefile | ||
| README.md | ||
| SECURITY.md | ||
| bin | ||
| package-lock.json | ||
| package.json | ||
| settings.json.docker | ||
| settings.json.template | ||
| start.bat | ||
| tests | ||
README.md
A real-time collaborative editor for the web
About
Etherpad is a real-time collaborative editor scalable to thousands of simultaneous real time users. It provides full data export capabilities, and runs on your server, under your control.
Installation
Requirements
nodejs>= 10.17.0.
GNU/Linux and other UNIX-like systems
Quick install on Debian/Ubuntu
curl -sL https://deb.nodesource.com/setup_14.x | sudo -E bash -
sudo apt install -y nodejs
git clone --branch master https://github.com/ether/etherpad-lite.git && cd etherpad-lite && bin/run.sh
Manual install
You'll need git and node.js installed (minimum required Node version: 10.17.0).
As any user (we recommend creating a separate user called etherpad):
- 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 - Change into the new directory containing the cloned source code:
cd etherpad-lite - run
bin/run.shand open http://127.0.0.1:9001 in your browser.
To update to the latest released version, execute git pull origin. The next start with bin/run.sh will update the dependencies.
Windows
Prebuilt Windows package
This package runs on any Windows machine, but for development purposes, please do a manual install.
- Download the latest Windows package
- Extract the folder
Run start.bat and open http://localhost:9001 in your browser. You like it? Next steps.
Manually install on Windows
You'll need node.js and (optionally, though recommended) git.
- Grab the source, either
- download https://github.com/ether/etherpad-lite/zipball/master
- or
git clone --branch master https://github.com/ether/etherpad-lite.git
- With a "Run as administrator" command prompt execute
bin\installOnWindows.bat
Now, run start.bat and open http://localhost:9001 in your browser.
Update to the latest version with git pull origin, then run bin\installOnWindows.bat, again.
If cloning to a subdirectory within another project, you may need to do the following:
- Start the server manually (e.g.
node/node_modules/ep_etherpad-lite/node/server.js) - Edit the db
filenameinsettings.jsonto the relative directory with the file (e.g.application/lib/etherpad-lite/var/dirty.db) - Add auto-generated files to the main project
.gitignore
Docker container
Find here information on running Etherpad in a container.
Next Steps
Tweak the settings
You can modify the settings in settings.json.
If you need to handle multiple settings files, you can pass the path to a settings file to bin/run.sh using the -s|--settings option: this allows you to run multiple Etherpad instances from the same installation.
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.
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.
Once you have access to your /admin section settings can be modified through the web browser.
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.
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 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.
Customize functionalities with plugins
Etherpad is very customizable through plugins. Instructions for installing themes and plugins can be found in the plugin wiki article.
Getting the full features
Run the following command in your Etherpad folder to get all of the features visible in the demo gif:
npm install ep_headings2 ep_markdown ep_comments_page ep_align ep_font_color ep_webrtc ep_embedded_hyperlinks2
Customize the style with skin variants
Open http://127.0.0.1:9001/p/test#skinvariantsbuilder in your browser and start playing !
Helpful resources
The wiki is your one-stop resource for Tutorials and How-to's.
Documentation can be found in doc/.
Development
Things you should know
You can debug Etherpad using bin/debugRun.sh.
You can run Etherpad quickly launching bin/fastRun.sh. It's convenient for developers and advanced users. Be aware that it will skip the dependencies update, so remember to run bin/installDeps.sh after installing a new dependency or upgrading version.
If you want to find out how Etherpad's Easysync works (the library that makes it really realtime), start with this PDF (complex, but worth reading).
Contributing
Read our Developer Guidelines
Get in touch
The official channel for contacting the development team is via the Github issues.
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
HTTP API
Etherpad is designed to be easily embeddable and provides a HTTP API that allows your web application to manage pads, users and groups. It is recommended to use the available client implementations in order to interact with this API.
OpenAPI (previously swagger) definitions for the API are exposed under /api/openapi.json.
jQuery plugin
There is a jQuery plugin that helps you to embed Pads into your website.
Plugin Framework
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 and take control.
Translations / Localizations (i18n / l10n)
Etherpad comes with translations into all languages thanks to the team at TranslateWiki.
If you require translations in plugins please send pull request to each plugin individually.
FAQ
Visit the FAQ.