Etherpad is a free and open-source alternative to services like Google Docs and Zoho Writer. Etherpad is a collaborative and real-time text editor for your team, it’s accessible from anywhere at any time because Etherpad is a web-based text editor.
Any changes on Etherpad are happening in real-time, and also etherpad is supports versioning and built-in formatting for teams. Etherpad is a highly customizable editor with the support of various plugins. And also supports modern document formats such as doc, pdf, odt, markdown, etc.
In this tutorial, you will install and configure the Etherpad Real-time Collaborative Editor on the Debian 11 Bullseye. This tutorial uses MariaDB as the database backend and Nginx web-server as a reverse proxy with the secure HTTPS enabled. In the end, you’ll have the Etherpad installed and secured through secure HTTPS encryption.
Prerequisites
In order to complete this tutorial, you’ll first need the following requirements:
- An Debian 11 server, for testing you can use 1 GB of RAM. For production, you can use more resources, depending on your environment and usage.
- A non-root user with root privileges. Optionally, you can use the root user.
- A domain name for the installation, and make sure it’s pointed to the server IP address. In this example, we’ll use the domain ‘etherpad.example.io‘.
When you’ve got all of these prerequisites, proceed to the first section to start the installation.
Installing Packages Dependencies
Etherpad is a web application built on top the Node.js. At the time of this writing, the Etherpad latest version is xxx, and required at least Node.js version 14.x. In this section, you’ll install some package dependencies, including Node.js to the Debian 11 server.
1. First, refresh your package index list, then install build dependencies by running the following command.
sudo apt update
sudo apt install gzip git curl python libssl-dev pkg-config gcc g make build-essential -y
2. In this tutorial, you’ll install Node.js from the Nodesource repository, which provides multiple versions of Node.js. This tutorial uses the Node.js version 16.x for the Etherpad installation.
Now, execute the following command to add the Node.js repository to your system. This command will automatically add the Nodesource repository to refresh your package index.
curl -sL https://deb.nodesource.com/setup_16.x | sudo -E bash -
3. Next, install Node.js 16.x from the Nodesource repository by running the command below.
sudo apt install nodejs -y
4. After installation is completed, verify your Node.js version using the following command.
node --version
You’ll receive an output such as ‘blah blah’.
In this section, you have installed packages dependencies for Etherpad and the Node.js version 16.x from the Nodesource repository. Next, you’ll install and configure the MariaDB database.
Installing and Configuring MariaDB Database
In this section, you’ll install the MariaDB database on the Debian 11 server. Then you’ll set up the root password for MariaDB, and lastly, you’ll create a new database and user for Etherpad.
1. By default, MariaDB packages are available on the Debian 11 repository. Run the following command to install it.
sudo apt install mariadb-server -y
2. When the MariaDB installation is completed, it will automatically be running and enabled.
MariaDB provides a command-line tool that helps you to deploy MariaDB securely, including setting up the root password for MariaDB. Execute the command ‘mysql_secure_installation’ as below.
mysql_secure_installation
Now you’ll be asked some questions related to MariaDB deployment and prompted to set up the root password.
3. The default root user for mariaDB has no password, press ENTER.
Enter current password for root (enter for none):
OK, successfully used password, moving on...
4. Now you’ll be asked to switch the authentication method using ‘unix_socket‘, type ‘Y‘ to agree.
Switch to unix_socket authentication [Y/n] Y
Enabled successfully!
Reloading privilege tables..
... Success!
5. Type ‘Y‘ to set up a new root password for MariaDB. Then input your strong password and repeat.
Change the root password? [Y/n] Y
New password:
Re-enter new password:
Password updated successfully!
Reloading privilege tables..
... Success!
6. The default MariaDB installation comes with an anonymous user. Type ‘Y’ to remove it.
Remove anonymous users? [Y/n] Y
... Success!
7. Now, disable remote login for the MariaDB root user. Type ‘Y‘ to agree.
Disallow root login remotely? [Y/n] Y
... Success!
8. Next, type ‘Y‘ to agree and remove the default database ‘test‘ and all privileges on top of it.
Remove test database and access to it? [Y/n] Y
- Dropping test database...
... Success!
- Removing privileges on test database...
... Success!
9. Lastly, reload table privileges to apply a new configuration. Type ‘Y‘ to agree and press ENTER.
Reload privilege tables now? [Y/n] Y
... Success!
When all configuration is completed, you’ll receive the output message such as ‘All done!‘ as below.
All done! If you've completed all of the above steps, your MariaDB
installation should now be secure.Thanks for using MariaDB!
10. Next, run the following command to log in to the MariaDB shell. You’ll be prompted for the MariaDB root password. Input your password.
mysql -u root -p
11. Now, create a new database and user for the Etherpad by running the following queries. This example will create a new database ‘etherpad_lite_db‘ with the user ‘etherpaduser‘ and password ‘StrongPasswordEtherpadDB‘. Be sure to change the password.
CREATE DATABASE etherpad_lite_db;
CREATE USER [email protected] IDENTIFIED BY 'StrongPasswordEtherpadDB';
GRANT CREATE,ALTER,SELECT,INSERT,UPDATE,DELETE on etherpad_lite_db.* to [email protected];
12. After that, reload all tables privileges to apply a new configuration, then run the ‘exit’ query to log out from the mariaDB shell.
FLUSH PRIVILEGES;
EXIT
In this section, you’ve completed the installation and configuration of the MariaDB database on Debian 11. Also, you’ve created the database and user for the Etherpad. Next, you’ll download the Etherpad source code and install it.
Installing and Configuring Etherpad
In this section, you’ll install the Etherpad from the source code, then configure it with MariaDB as the database, and create a new systemd file for the Etherpad. In the end, the Etherpad will be running as a systemd service.
1. Before downloading Etherpad source code you’re going to create a new user ‘etherpad‘ on your system. This user will be used to run the Etherpad installer script and run the Etherpad service.
Execute the ‘adduser‘ command below to create a new user ‘etherpad‘. Also, define the home directory to ‘/opt/etherpad-lite‘. This directory will be used to store all Etherpad sources.
sudo adduser --system --no-create-home --home=/opt/etherpad-lite --group etherpad
2. Now, navigate to the directory ‘/opt‘ and clone the Etherpad source using the git command.
cd /opt/
git clone --branch master https://github.com/ether/etherpad-lite.git
3. After that, change the ownership of the ‘etherpad-lite’ directory to the user ‘etherpad‘ and group ‘etherpad‘.
sudo chown -R etherpad:etherpad etherpad-lite
4. Now navigate to the directory ‘etherpad-lite/‘ and install all Node.js dependencies using the installer script ‘installDeps.sh’ as below. The installer script ‘installDeps.sh‘ will be running as a non-root user ‘etherpad’.
cd /opt/etherpad-lite
sudo su -s /bin/bash -c "./bin/installDeps.sh" etherpad
Wait for all packages dependencies installation is completed.
Next, modify the file ‘settings.json‘ to set up your Etherpad installation. You can use a nano editor to edit that file or use your preferred editor.
nano settings.json
At the top of the line, change the title with your own title. This example uses the title ‘Entherpad Johndoe‘.
"title": "Etherpad Johndoe",
In this tutorial, the Etherpad will be running under the Nginx reverse proxy. And it’s good for security to run the Etherpad on the localhost. Now, change the ‘ip:’ configuration to ‘127.0.0.1′. With this configuration, the Etherpad will be running on the localhost only.
"ip": "127.0.0.1",
"port": 9001,
By default, the Etherpad uses SQLite as the database. Comment all of these lines to disable.
/*
*"dbType": "dirty",
*"dbSettings": {
* "filename": "var/dirty.db"
*},
*/
Now, input the MariaDB database configuration below. And make sure to change the database name, user, and password.
"dbType" : "mysql",
"dbSettings" : {
"user": "etherpaduser",
"host": "localhost",
"port": 3306,
"password": "StrongPasswordEtherpadDB",
"database": "etherpad_lite_db",
"charset": "utf8mb4"
},
Save and exit the file.
Next, create a new systemd service file ‘etherpad.service‘ in the directory ‘/etc/systemd/system‘. This file will contain all configuration details that Etherpad needs to run properly on the server. Create it using a nano editor.
sudo nano /etc/systemd/system/etherpad.service
Add the following configuration into the file.
[Unit]
Description=Etherpad-lite, the collaborative editor.
After=syslog.target network.target[Service]
Type=simple
User=etherpad
Group=etherpad
WorkingDirectory=/opt/etherpad-lite
Environment=NODE_ENV=production
ExecStart=/usr/bin/node --experimental-worker /opt/etherpad-lite/node_modules/ep_etherpad-lite/node/server.js
# use mysql plus a complete settings.json to avoid Service hold-off time over, scheduling restart.
Restart=always[Install]
WantedBy=multi-user.target
This service file will be running as a user and group ‘etherpad’. And you’ll notice the option ‘Environment=NODE_ENV=production‘, which means the Etherpad application will be running on the production environment. The ‘ExecStart=..‘ option is the default command to run the Etherpad application.
Save and close the file.
Now, reload the systemd manager to apply a new service file.
sudo systemctl daemon-reload
After that, start and enable the etherpad service, then verify its status by running the following command.
sudo systemctl enable --now etherpad
sudo systemctl status etherpad
You’ll receive the output similar to the screenshot below. The etherpad service is now ‘active (running)‘, it will automatically start at the system startup, and it’s running on the localhost with default port ‘9001‘.
At this point, you have completed the Etherpad installation. Next, you’ll install Nginx set up it as a reverse proxy for the Etherpad application.
Installing and Configuring Nginx
For the production environment, it is always recommended to put a reverse proxy in front of your application. It will increase your application performance and security. In this section, you’ll install and configure the Nginx web server as a reverse proxy. In the end, you’ll have the Etherpad running with your domain name and secured with HTTPS protocol.
1. At first, install Nginx packages by running the command below.
sudo apt install nginx -y
2. Now, if you have got the UFW firewall on your Debian system. Allow public access to the HTTP and HTTPS ports (80 and 443) by running the ‘ufw‘ command below.
sudo ufw allow "Nginx Full"
You’ll receive the following output.
Rule added
Rule added (v6)
3. Next, create a new Nginx virtual host file ‘etherpad‘ in the directory ‘/etc/nginx/sites-available/‘. Create it using a nano editor or your preferred editor.
sudo nano /etc/nginx/sites-available/etherpad
Copy and paste the following configuration into the file. Also, replace your domain name and SSL certificate path with your own information. For SSL certificates, you can generate SSL certificates freely using Letsencrypt.
# enforce HTTPS
server {
listen 80;
listen [::]:80;
server_name etherpad.example.io;
return 301 https://$host$request_uri;
}# we're in the http context here
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}server {
listen 443 ssl http2;
listen [::]:443 ssl http2;
server_name etherpad.example.io;access_log /var/log/nginx/eplite.access.log;
error_log /var/log/nginx/eplite.error.log;ssl_certificate /etc/letsencrypt/live/etherpad.example.io/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/etherpad.example.io/privkey.pem;ssl_session_timeout 5m;
ssl_protocols TLSv1.2;
ssl_prefer_server_ciphers on;
ssl_ciphers "EECDH ECDSA AESGCM EECDH aRSA AESGCM EECDH ECDSA SHA384
EECDH ECDSA SHA256 EECDH aRSA SHA384 EECDH aRSA SHA256 EECDH aRSA RC4
EECDH EDH aRSA RC4 !aNULL !eNULL !LOW !3DES !MD5 !EXP !PSK !SRP !DSS";location / {
proxy_pass http://127.0.0.1:9001;
proxy_buffering off; # be careful, this line doesn't override any proxy_buffering on set in a conf.d/file.conf
proxy_set_header Host $host;
proxy_pass_header Server;# Note you might want to pass these headers etc too.
proxy_set_header X-Real-IP $remote_addr; # https://nginx.org/en/docs/http/ngx_http_proxy_module.html
proxy_set_header X-Forwarded-For $remote_addr; # EP logs to show the actual remote IP
proxy_set_header X-Forwarded-Proto $scheme; # for EP to set secure cookie flag when https is used
proxy_http_version 1.1; # recommended with keepalive connections# WebSocket proxying - from https://nginx.org/en/docs/http/websocket.html
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
}
}
This Nginx virtual host file will automatically redirect any traffic from HTTP to the secure HTTPS protocol. For debugging in case you have an error, check the log file ‘/var/log/nginx/eplite.error.log‘. All client requests will be sent to the backend ‘proxy_pass‘ the Etherpad application that running on localhost port 9001.
4. Save and close the file, then activate the virtual host configuration by creating a symbolic link of file ‘etherpad‘ to the directory ‘/etc/nginx/sites-enabled‘.
sudo ln -s /etc/nginx/sites-available/etherpad /etc/nginx/sites-enabled/
5. Next, run the command ‘nginx -t’ to verify the nginx configuration. This command will check any syntax error on the configuration.
sudo nginx -t
You’ll receive output as below. The output message ‘syntax is ok‘ means you don’t have any errors.
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful.
6. Lastly, restart the Nginx service to apply a new Nginx virtual host file.
sudo systemctl restart nginx
In this section, you have completed the Nginx installation and configuration as a reverse proxy for the Etherpad application. Your Etherpad is now available on http://etherpad.example.io.
Verify Etherpad Installation
1. Open your web browser and type the domain name ‘http://etherpad.example.io/‘ on the address. And you’ll automatically be redirected to the secure HTTPS connection as below.
2. To create a new pad, input the name of the pad on the column and click the button ‘OK‘.
Now you’ll see the Etherpad Real-time Collaboration Editor as below.
Conclusion
In this tutorial, you’ve installed and configured the Etherpad Real-time Collaborative Editor on the Debian 11 server. Also, you’ve installed and configured Nginx as a reverse proxy for the Etherpad application.
You’re now ready to use etherpad as your collaboration editor in your team. For further information about Etherpad, check the official Etherpad documentation.
