mirror of
https://github.com/ether/etherpad-lite.git
synced 2025-01-19 14:13:34 +01:00
2f39a7b4bb
file in the root directory that references ./src directory as the file source for `ep_etherpad-lite`. Remove --legacy-peer-deps and --no-save when invoking npm. There is no need for them anymore, as we are bumping npm now to v8. ./src/package.json contains all dependencies of Etherpad core (package name ep_etherpad-lite) as before. The root directory's package.json file references ep_etherpad-lite and also contains references to any installed plugins. Remove npm from package.json as we depend on a recent version now; PATH is still updated as before, so in the future we may install a custom npm version again lint package-lock: update exception for sqlite3 remove node_modules and package.json during installDeps.sh update Dockerfile adapt minify windows build Fixed installOnWindows.bat remove node_modules from git bump minimal node/npm version in src/bin/functions.sh add changelog notes update installdeps fix dockerfile docker: test npm prefix set to the etherpad directory workflow: upgrade-from-latest-release needs to be adapted until next release is out Revert "docker: test npm prefix set to the etherpad directory" This reverts commit b856a2488c9dbfb2acf35309cd1ee83016b631ad. use npm link --bin-links=false to prevent it from copying bin files temp fix for scripts as they are not installed to bin directory anymore adjust bin paths in Dockerfile Dockerfile add hint for npm link, dockerfile update dockerfile Revert "Fixed installOnWindows.bat" This reverts commit 70d0716bbedc4c0c1043155fcc5d157f01775c61. try installOnWindows; still TODO: no difference between production and development; no warning like in installDeps.sh before update - it just removes package* and node_modules so admins must be aware of the plugins they want to reinstall later update installOnWindows.bat update package-lock.json Dockerfile Dockerfile add file: scheme for lint check - needed as long as we have the plugin compatibility symlinks in ./src/node_modules fix installOnWindows upgrade-from-latest-release workflow: adapt cypress installation src/package.json: test-container fix path to _mocha; maybe revert this in case we enable bin-links again src/package.json: add test-on-windows script another try with test-on-windows, without using bin-links use bin-links on windows Revert "use bin-links on windows" This reverts commit f50ec2a9fabe3098d48e8f412b73c01edbe2140e. invoke mocha binary on windows run npm i once on windows, to make bin files available - why? remove supertest on windows production builds add symlink for mocha debug Revert "debug" This reverts commit 8916a0515ca2897c57ca65fef49fd0b3610d2989. Revert "add symlink for mocha" This reverts commit 3c60bef77d2a120d24fce14421fe638598cd849d. windows workflow: adapt cypress path frontend admin tests
294 lines
12 KiB
Markdown
294 lines
12 KiB
Markdown
# Etherpad: A real-time collaborative editor for the web
|
|
|
|
|
|
|
|
## About
|
|
|
|
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.
|
|
|
|
## Try it out
|
|
|
|
Wikimedia provide a [public Etherpad instance for you to Try Etherpad out.](https://etherpad.wikimedia.org) or [use another public Etherpad instance to see other features](https://github.com/ether/etherpad-lite/wiki/Sites-That-Run-Etherpad#sites-that-run-etherpad)
|
|
|
|
## Project Status
|
|
|
|
We're looking for maintainers and have some funding available. Please contact John McLear if you can help.
|
|
|
|
### Code Quality
|
|
|
|
[](https://github.com/ether/etherpad-lite/actions/workflows/codeql-analysis.yml)
|
|
[](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/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)
|
|
[](https://saucelabs.com/u/etherpad)
|
|
[](https://github.com/ether/etherpad-lite/actions/workflows/windows.yml)
|
|
|
|
### Engagement
|
|
|
|
[](https://hub.docker.com/r/etherpad/etherpad)
|
|
[](https://discord.com/invite/daEjfhw)
|
|
[](https://static.etherpad.org/index.html)
|
|
|
|
|
|
|
|
## Installation
|
|
|
|
### Requirements
|
|
|
|
[Node.js](https://nodejs.org/) >= **16.20.1**.
|
|
|
|
### GNU/Linux and other UNIX-like systems
|
|
|
|
#### Quick install on Debian/Ubuntu
|
|
|
|
```sh
|
|
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 &&
|
|
src/bin/run.sh
|
|
```
|
|
|
|
#### Manual install
|
|
|
|
You'll need Git and [Node.js](https://nodejs.org/) installed.
|
|
|
|
**As any user (we recommend creating a separate user called etherpad):**
|
|
|
|
1. Move to a folder where you want to install Etherpad.
|
|
2. Clone the Git repository: `git clone --branch master
|
|
https://github.com/ether/etherpad-lite.git`
|
|
3. Change into the new directory containing the cloned source code: `cd
|
|
etherpad-lite`
|
|
4. Run `src/bin/run.sh` and 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 `src/bin/run.sh` will update the dependencies.
|
|
|
|
### Windows
|
|
|
|
#### Prebuilt Windows package
|
|
|
|
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.
|
|
|
|
1. [Download the latest Windows package](https://etherpad.org/#download)
|
|
2. Extract the folder
|
|
|
|
Run `start.bat` and open <http://localhost:9001> in your browser.
|
|
|
|
#### Manually install on Windows
|
|
|
|
You'll need [Node.js](https://nodejs.org) and (optionally, though recommended)
|
|
git.
|
|
|
|
1. 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`
|
|
2. With a "Run as administrator" command prompt execute
|
|
`src\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
|
|
`src\bin\installOnWindows.bat`, again.
|
|
|
|
If cloning to a subdirectory within another project, you may need to do the
|
|
following:
|
|
|
|
1. Start the server manually (e.g. `node src/node/server.js`)
|
|
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`
|
|
|
|
### Docker container
|
|
|
|
Find [here](doc/docker.adoc) information on running Etherpad in a container.
|
|
|
|
## Plugins
|
|
|
|
Etherpad is very customizable through plugins.
|
|
|
|
|
|
|
|
|
|
|
|
### Available Plugins
|
|
|
|
For a list of available plugins, see the [plugins
|
|
site](https://static.etherpad.org).
|
|
|
|
### Plugin Installation
|
|
|
|
You can install plugins from the admin web interface (e.g.,
|
|
http://127.0.0.1:9001/admin/plugins).
|
|
|
|
Alternatively, you can install plugins from the command line:
|
|
|
|
```sh
|
|
cd /path/to/etherpad-lite
|
|
npm install ep_${plugin_name}
|
|
```
|
|
|
|
Also see [the plugin wiki
|
|
article](https://github.com/ether/etherpad-lite/wiki/Available-Plugins).
|
|
|
|
### Suggested Plugins
|
|
|
|
Run the following command in your Etherpad folder to get all of the features
|
|
visible in the above demo gif:
|
|
|
|
```sh
|
|
npm install \
|
|
ep_align \
|
|
ep_comments_page \
|
|
ep_embedded_hyperlinks2 \
|
|
ep_font_color \
|
|
ep_headings2 \
|
|
ep_markdown \
|
|
ep_webrtc
|
|
```
|
|
|
|
For user authentication, you are encouraged to run an [OpenID
|
|
Connect](https://openid.net/connect/) identity provider (OP) and install the
|
|
following plugins:
|
|
|
|
* [ep_openid_connect](https://github.com/ether/ep_openid_connect#readme) to
|
|
authenticate against your OP.
|
|
* [ep_guest](https://github.com/ether/ep_guest#readme) to create a
|
|
"guest" account that has limited access (e.g., read-only access).
|
|
* [ep_user_displayname](https://github.com/ether/ep_user_displayname#readme)
|
|
to automatically populate each user's displayed name from your OP.
|
|
* [ep_stable_authorid](https://github.com/ether/ep_stable_authorid#readme) so
|
|
that each user's chosen color, display name, comment ownership, etc. is
|
|
strongly linked to their account.
|
|
|
|
## 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 `src/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](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.
|
|
|
|
### 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](https://github.com/ether/etherpad-lite/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 `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.
|
|
|
|
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).
|
|
|
|
### Contributing
|
|
|
|
Read our [**Developer
|
|
Guidelines**](https://github.com/ether/etherpad-lite/blob/master/CONTRIBUTING.md)
|
|
|
|
### HTTP API
|
|
|
|
Etherpad is designed to be easily embeddable and provides a [HTTP
|
|
API](https://github.com/ether/etherpad-lite/wiki/HTTP-API) 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.
|
|
|
|
OpenAPI (previously swagger) definitions for the API are exposed under
|
|
`/api/openapi.json`.
|
|
|
|
### jQuery plugin
|
|
|
|
There is a [jQuery plugin](https://github.com/ether/etherpad-lite-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](https://static.etherpad.org/) and take control.
|
|
|
|
### Translations / Localizations (i18n / l10n)
|
|
|
|
Etherpad comes with translations into all languages thanks to the team at
|
|
[TranslateWiki](https://translatewiki.net/).
|
|
|
|
If you require translations in [plugins](https://static.etherpad.org/) please
|
|
send pull request to each plugin individually.
|
|
|
|
## FAQ
|
|
|
|
Visit the **[FAQ](https://github.com/ether/etherpad-lite/wiki/FAQ)**.
|
|
|
|
## Get in touch
|
|
|
|
The official channel for contacting the development team is via the [GitHub
|
|
issues](https://github.com/ether/etherpad-lite/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](https://discord.com/invite/daEjfhw).
|
|
|
|
## License
|
|
|
|
[Apache License v2](http://www.apache.org/licenses/LICENSE-2.0.html)
|