How To Install Etherpad on Debian 12

Collaborative document editing has become essential for teams working remotely or in distributed environments. Etherpad stands out as a powerful, open-source real-time collaborative text editor that allows multiple users to edit documents simultaneously. Unlike proprietary solutions such as Google Docs, Etherpad gives you complete control over your data while offering robust features including change tracking, version control, and customizable plugins.

This comprehensive guide walks you through the process of installing and configuring Etherpad on a Debian 12 server. By following these instructions, you’ll have a secure, optimized, and fully functional collaborative editing platform that your team can use for various projects.

Prerequisites

Before beginning the installation process, ensure you have the following:

• A Debian 12 server with at least 1GB RAM (2GB or more recommended for production use)
• A domain name properly configured to point to your server’s IP address
• A non-root user with sudo privileges for security best practices
• Basic familiarity with command-line operations
• TCP ports 9001 (for Etherpad), 80 (HTTP), and 443 (HTTPS) available on your server

Having these prerequisites in place will ensure a smoother installation process and help avoid common pitfalls that might arise during setup.

System Preparation

To prepare your Debian 12 system for Etherpad installation, start by updating your package repositories and upgrading existing packages to their latest versions:

sudo apt update
sudo apt upgrade -y

This ensures your system has the most recent security patches and software versions. Next, install essential system utilities and build tools that Etherpad and its dependencies require:

sudo apt install gzip git curl python3 libssl-dev pkg-config build-essential -y

These packages provide the necessary development libraries and tools required for compiling and running Etherpad’s components. Setting your system’s timezone correctly can help with proper logging and scheduling:

sudo timedatectl set-timezone Your/Timezone

Replace “Your/Timezone” with your appropriate time zone (e.g., “America/New_York” or “Europe/London”).

Installing Dependencies

Etherpad relies on several key dependencies to function properly. The most crucial components include Node.js, NPM, and a database system.

First, install the required packages:

sudo apt install mariadb-server nginx ufw nodejs npm -y

After installation, verify that Node.js was installed correctly:

nodejs --version

The output should display version 18 or newer, which is required for current Etherpad versions. If you need a newer version of Node.js than what’s available in the Debian repositories, you can use Node Version Manager (NVM):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc
nvm install 18

This gives you more flexibility in managing Node.js versions if needed.

Next, check that MariaDB is running and enabled:

sudo systemctl is-enabled mariadb
sudo systemctl status mariadb

The output should indicate that MariaDB is both enabled and active (running). If not, start and enable it:

sudo systemctl start mariadb
sudo systemctl enable mariadb

Database Setup

Etherpad can use various database backends, but MariaDB (MySQL) provides better performance for production environments compared to the default SQLite option.

First, secure your MariaDB installation:

sudo mysql_secure_installation

Follow the prompts to set a root password, remove anonymous users, disallow root login remotely, and remove the test database.

Next, log in to the MariaDB shell to create a dedicated database and user for Etherpad:

sudo mysql -u root -p

Enter your MariaDB root password, then execute the following SQL commands:

CREATE DATABASE etherpad_lite;
CREATE USER 'etherpad'@'localhost' IDENTIFIED BY 'your_secure_password';
GRANT ALL PRIVILEGES ON etherpad_lite.* TO 'etherpad'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Replace ‘your_secure_password’ with a strong, unique password for the Etherpad database user. This creates a dedicated database called “etherpad_lite” and a user that has permission to manage only that specific database, following security best practices.

Creating Etherpad User and Downloading Source

For security and maintenance reasons, Etherpad should run under its own dedicated system user rather than as root or your regular user account.

Create a dedicated system user called “etherpad“:

sudo adduser --system --no-create-home --home=/opt/etherpad-lite --group etherpad

This command creates a system user that:

• Cannot log in directly (no password)
• Has no regular home directory
• Uses /opt/etherpad-lite as its home directory
• Belongs to its own group of the same name

Now download the Etherpad source code from the official GitHub repository:

cd /opt && sudo git clone --branch master https://github.com/ether/etherpad-lite.git

After downloading, set the correct ownership of the Etherpad directory:

sudo chown -R etherpad:etherpad /opt/etherpad-lite

This ensures that the etherpad user has proper permissions to access and modify all files in the installation directory.

Installing Etherpad Core

With the source code downloaded, you can now install Etherpad’s core components and dependencies.

Navigate to the installation directory:

cd /opt/etherpad-lite

Run the installation script as the etherpad user:

sudo su -s /bin/bash -c "./bin/run.sh" etherpad

This command runs the Etherpad script as the etherpad user. The script automatically installs required Node.js dependencies and starts Etherpad with the default configuration.

You’ll see output indicating that Etherpad is downloading dependencies and starting up. Once it displays a message that Etherpad is running and accessible at http://0.0.0.0:9001/, press Ctrl+C to stop the process so you can configure it properly.

Configuring Etherpad

The next step is to configure Etherpad according to your needs by modifying the settings.json file:

sudo nano /opt/etherpad-lite/settings.json

The configuration file contains numerous settings, but here are the essential ones you should modify:

1. Change the title of your Etherpad installation:

"title": "Your Etherpad Title",

2. Set Etherpad to listen on localhost only for security (since we’ll use Nginx as a reverse proxy):

"ip": "127.0.0.1",
"port": 9001,

3. Configure the database connection to use MariaDB instead of the default SQLite:

"dbType": "mysql",
"dbSettings": {
  "user": "etherpad",
  "host": "localhost",
  "password": "your_secure_password",
  "database": "etherpad_lite",
  "charset": "utf8mb4"
},

4. Adjust session settings for security:

"sessionKey": "a_very_long_random_string_for_session_security",

Replace “your_secure_password” with the password you created earlier for the etherpad MariaDB user, and generate a random string for the sessionKey.

Save and close the file after making your changes.

Setting Up Systemd Service

To ensure Etherpad runs automatically at system startup and can be managed easily, create a systemd service:

sudo nano /etc/systemd/system/etherpad.service

Add the following content to the file:

[Unit]
Description=Etherpad, a collaborative web editor
After=syslog.target network.target mariadb.service

[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
Restart=always

[Install]
WantedBy=multi-user.target

This service definition specifies that:

• Etherpad should start after network services and MariaDB are running
• The service runs as the etherpad user and group
• Node.js runs Etherpad’s server script
• If the service crashes, it will automatically restart

Save and close the file, then reload the systemd configuration:

sudo systemctl daemon-reload

Now start and enable the Etherpad service:

sudo systemctl start etherpad
sudo systemctl enable etherpad

Verify that the service is running correctly:

sudo systemctl status etherpad

You should see output indicating that the service is active and running. You can also check that Etherpad is listening on port 9001:

ss -tulpn | grep 9001

Nginx Reverse Proxy Setup

While Etherpad is now running, it’s best practice to use Nginx as a reverse proxy for improved security, performance, and to enable SSL/TLS.

First, create an Nginx server block configuration:

sudo nano /etc/nginx/sites-available/etherpad

Add the following configuration:

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:9001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Replace “your-domain.com” with your actual domain name. This configuration forwards requests to the Etherpad service running on localhost port 9001, while preserving important headers for proper operation.

Create a symbolic link to enable this configuration:

sudo ln -s /etc/nginx/sites-available/etherpad /etc/nginx/sites-enabled/

Test the Nginx configuration for syntax errors:

sudo nginx -t

If the test is successful, restart Nginx to apply the changes:

sudo systemctl restart nginx

Securing with SSL/TLS

To encrypt traffic between users and your Etherpad server, install Certbot to obtain a free SSL certificate from Let’s Encrypt:

sudo apt install certbot python3-certbot-nginx -y

Obtain and configure an SSL certificate:

sudo certbot --nginx -d your-domain.com

Follow the prompts to complete the certificate issuance process. Certbot will automatically modify your Nginx configuration to use HTTPS.

Verify that automatic certificate renewal is configured:

sudo systemctl status certbot.timer

This ensures your SSL certificate will be renewed automatically before it expires.

Firewall Configuration

Setting up a firewall adds an additional layer of security to your server. UFW (Uncomplicated Firewall) makes this process straightforward:

sudo apt install ufw -y

Configure UFW to allow SSH, HTTP, and HTTPS traffic:

sudo ufw allow ssh
sudo ufw allow http
sudo ufw allow https

Enable the firewall:

sudo ufw enable

Verify the firewall status:

sudo ufw status

The output should show that SSH (port 22), HTTP (port 80), and HTTPS (port 443) are allowed, while all other incoming connections are blocked by default.

Testing the Installation

Now that Etherpad is installed, configured, and secured, it’s time to test it:

1. Open a web browser and navigate to your domain (https://your-domain.com)
2. You should see the Etherpad welcome page
3. Create a new pad by clicking “New Pad” or by appending “/p/pad-name” to your domain URL
4. Test the real-time collaboration by opening the same pad URL in another browser or device
5. Verify that changes made in one browser appear almost instantly in the other

Check that the editor toolbar functions correctly and that you can perform basic formatting tasks. Test the time slider feature to view the document’s revision history.

Advanced Configuration

Etherpad’s functionality can be extended through plugins and additional configuration options.

Customizing the User Interface:

You can modify the appearance by editing the CSS or installing themes. In settings.json, you can set:

"skinName": "colibris",

Installing Plugins:

Etherpad’s plugin system allows for easy extension of functionality:

cd /opt/etherpad-lite
sudo -u etherpad npm install ep_align ep_font_color ep_headings

This installs plugins for text alignment, font colors, and headings. Restart Etherpad after installing plugins:

sudo systemctl restart etherpad

Authentication Options:

For a private Etherpad instance, you can enable user authentication by modifying settings.json:

"requireAuthentication": true,
"requireAuthorization": true,
"users": {
  "admin": {
    "password": "changeme",
    "is_admin": true
  },
  "user": {
    "password": "changeme",
    "is_admin": false
  }
}

For more complex authentication needs, consider plugins like ep_ldapauth for LDAP integration.

Maintenance and Backups

Regular maintenance ensures your Etherpad installation remains secure and performs optimally.

Updates:

To update Etherpad to the latest version:

cd /opt/etherpad-lite
sudo git pull
sudo chown -R etherpad:etherpad .
sudo systemctl restart etherpad

Database Backups:

Create regular database backups:

sudo mysqldump -u root -p etherpad_lite > etherpad_backup_$(date +%Y%m%d).sql

Log Management:

Configure log rotation to prevent logs from consuming too much disk space:

sudo nano /etc/logrotate.d/etherpad

Add the following configuration:

/opt/etherpad-lite/var/log/*.log {
  weekly
  missingok
  rotate 52
  compress
  delaycompress
  notifempty
  create 640 etherpad etherpad
}

Troubleshooting Common Issues

Connection Problems:

If you can’t access Etherpad through your browser:

• Check that the etherpad service is running: sudo systemctl status etherpad
• Verify Nginx is running: sudo systemctl status nginx
• Confirm your firewall settings: sudo ufw status
• Check Nginx error logs: sudo tail -f /var/log/nginx/error.log

Database Connectivity Issues:

If Etherpad can’t connect to the database:

• Verify MariaDB is running: sudo systemctl status mariadb
• Check database credentials in settings.json
• Ensure the etherpad database user has the correct permissions

Permission-Related Errors:

If you encounter permission errors in the logs:

• Verify ownership of the Etherpad directory: ls -la /opt/etherpad-lite
• Correct permissions if needed: sudo chown -R etherpad:etherpad /opt/etherpad-lite

Performance Issues:

For slow performance:

• Check server resource usage: top or htop
• Consider increasing RAM if available
• Optimize MySQL configuration for your server specifications

Congratulations! You have successfully installed Etherpad. Thanks for using this tutorial for installing the latest version of the Etherpad on Debian 12 “Bookworm”. For additional help or useful information, we recommend you check the official Etherpad website.