thisistaimur / etherpad-lite-heroku

Etherpad-Lite Heroku

Deploy Etherpad-Lite on Heroku. Whole Etherpad-Lite configuration, including plugins, can be specified in Heroku configuration variables (ENV).

Running

Cloning

=======

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.

Try it out

6a0f73d1379b4b97df1ffb20566f64eac3b09ccc

As the project has Etherpad as submodule, you need to clone it with --recursive flag:

git clone --recursive https://github.com/citizenos/etherpad-lite-heroku.git

Configuration

Configuration can be specified in 2 ways:

• File (config/local.json) - designed for development environments where file configuration is simpler to maintain than env variables. See the example local.json
• Environment variables - this is where all Heroku configuration variables show up. =======

Requirements

• nodejs >= 10.13.0.

GNU/Linux and other UNIX-like systems

Quick install on Debian/Ubuntu

curl -sL https://deb.nodesource.com/setup_10.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.13.0).

As any user (we recommend creating a separate user called etherpad):

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
2. Change into the new directory containing the cloned source code: cd etherpad-lite
3. run 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 bin/run.sh will update the dependencies.

Next steps.

Windows

Prebuilt Windows package

This package runs on any Windows machine, but for development purposes, please do a manual install.

1. Download the latest Windows package
2. 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.

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 bin\installOnWindows.bat

6a0f73d1379b4b97df1ffb20566f64eac3b09ccc

NOTE: Environment variables override config/local.json.

Etherpad-Lite configuration variables

In Heroku config variables (ENV):

• ETHERPAD_SETTINGS - JSON string of the whole standard Etherpad-Lite settings.json.
• ETHERPAD_SESSION_KEY - The secret stored in Etherpad-Lite SESSIONKEY.txt.
• ETHERPAD_API_KEY - The secret stored in Etherpad-Lite APIKEY.txt.
• DATABASE_URL - Default database URI environment variable set by Heroku. It overrides all other DB configurations.

<<<<<<< HEAD JSON defined in ETHERPAD_SETTINGS or config/local.json:

• ___apiKey - The secret stored in Etherpad-Lite APIKEY.txt.
• ___sessionKey - The secret stored in Etherpad-Lite SESSIONKEY.txt.
• ___version - Per plugin configuration. Version of plugin to be installed by NPM.

Plugin configuration

=======

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.

6a0f73d1379b4b97df1ffb20566f64eac3b09ccc

Plugin version and configuration can be specified. Plugins are configured as you would normally do in Etherpad-Lite settings.json, but you can also specify plugin version which will be installed by NPM.

• ___version - version of the plugin to be installed.

<<<<<<< HEAD Example plugin config in ETHERPAD_SETTINGS or config/local.json:

  "ep_themes_ext": {
    "___version": "0.0.4",
    "default": [
      "https://dev.citizenos.com:3001/static/styles/etherpad.css"
    ]
  }

Etherpad-Lite Heroku specific conf

• ETHERPAD_LITE_HEROKU_LOGGER_LEVEL - Logging level for the start.js script.

Run

Heroku

=======

Customize functionalities with plugins

Etherpad is very customizable through plugins. Instructions for installing themes and plugins can be found in the plugin wiki article.

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 maintainer ([email protected]).

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.

6a0f73d1379b4b97df1ffb20566f64eac3b09ccc

Push it to your Heroku and Heroku will just run it picking up the entry point from Procfile

Locally

<<<<<<< HEAD

• npm run start-dev

NOTE: When running locally with Citizen OS API, you may run into issues with certificate chain validation because of the API calls. In that case for DEV ONLY you can turn off the validation starting the app NODE_TLS_REJECT_UNAUTHORIZED=0 npm run start-dev. NOTE2: DO NOT commit the generated package.json. If generated plugin configuration is in the package.json /config/ has no effect.

Credits

• This project started as a fork of https://github.com/bright-star/etherpad-lite-heroku and basic concepts are borrowed from there.
• CitizenOS for funding the development =======

License

Apache License v2

6a0f73d1379b4b97df1ffb20566f64eac3b09ccc