Jul 11, 2024 3 min read

Etherpad: The Ultimate Guide to Self-Hosting

Etherpad: The Ultimate Guide to Self-Hosting
Table of Contents

Etherpad is a lightweight, open-source, collaborative text editor that allows multiple users to edit documents in real-time. Designed for customization and privacy, it’s an excellent choice for self-hosting, giving you full control over your data and configurations. In this guide, you’ll learn how to install, configure, secure, debug, back up, and customize Etherpad for your needs.

Installing Etherpad

πŸ“¦ Docker/Docker Compose Setup

Docker is the easiest way to deploy Etherpad. Below is a docker-compose.yml file tailored for Etherpad:


version: '3.7'

services:

etherpad:

image: etherpad/etherpad:latest

container_name: etherpad

ports:

- "9001:9001"

environment:

- ADMIN_PASSWORD=your_secure_password

- TITLE=My Etherpad Instance

- SKIN_NAME=colibris

volumes:

- ./data:/opt/etherpad-lite/var

restart: always

To deploy Etherpad using Docker Compose, run the following commands:


mkdir etherpad && cd etherpad

## Add the docker-compose.yml file

nano docker-compose.yml

## Start the Etherpad container

docker-compose up -d

## Verify the container is running

docker ps

πŸš€ Manual Installation

For those who prefer direct installation on a Linux server, here’s how to set it up manually:


## Update your package list and install dependencies

sudo apt update

sudo apt install -y nodejs npm git curl gzip

## Clone the Etherpad repository

git clone --branch master https://github.com/ether/etherpad-lite.git etherpad

cd etherpad

## Install required Node.js modules

npm install --legacy-peer-deps

## Run Etherpad

npm start

Access Etherpad by navigating to http://<your_server_ip>:9001 in your browser.

Configuring Nginx as a Reverse Proxy

🌐 Nginx Configuration

To serve Etherpad over a public domain, configure Nginx as a reverse proxy. Create a new Nginx server block:


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

Add the following configuration:


server {

listen 80;

server_name your-domain.com;

location / {

proxy_pass http://localhost:9001;

proxy_http_version 1.1;

proxy_set_header Upgrade $http_upgrade;

proxy_set_header Connection 'upgrade';

proxy_set_header Host $host;

proxy_cache_bypass $http_upgrade;

}

}

Enable the configuration and restart Nginx:


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

sudo nginx -t

sudo systemctl restart nginx

πŸ”’ SSL/TLS Setup

Secure your Etherpad instance with Let’s Encrypt:


## Install Certbot

sudo apt install -y certbot python3-certbot-nginx

## Obtain and configure SSL certificates

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

## Automate certificate renewal

sudo systemctl enable certbot.timer

Test your SSL configuration by visiting https://your-domain.com.

Logging and Debugging Etherpad

πŸ—ƒοΈ Enabling Debug Logs

To enable debug logging, edit settings.json in your Etherpad directory:


nano settings.json

Set the following value:


"loglevel": "DEBUG",

Restart Etherpad to apply the change:


npm stop && npm start

πŸ“„ Viewing Logs

View logs for a Docker deployment:


docker logs etherpad

Or, for a manual setup:


tail -f var/log/etherpad.log

πŸ› οΈ Troubleshooting Common Issues

Check for errors in logs related to missing dependencies or misconfigurations. For example, if Etherpad fails to start, ensure all required Node.js modules are installed.


npm install --legacy-peer-deps

πŸ“€ Exporting Logs

Forward logs to an external system like ELK:


## Install Filebeat or similar log forwarder

sudo apt install filebeat

## Configure Etherpad logs in Filebeat

sudo nano /etc/filebeat/filebeat.yml

Backup and Restore

πŸ—‚οΈ File-Based Backups

Backup the Etherpad directory (manual setup):


tar -czvf etherpad-backup.tar.gz /path/to/etherpad

πŸ”„ Database Backups

If using a database like MySQL, back it up with:


mysqldump -u root -p etherpad_db > etherpad_db_backup.sql

Restore it with:


mysql -u root -p etherpad_db < etherpad_db_backup.sql

πŸ“… Automated Backup Scripts

Set up a cron job for periodic backups:


crontab -e

Add the following line to back up daily at midnight:


0 0 * * * tar -czvf /backups/etherpad-$(date +\%F).tar.gz /path/to/etherpad

Updating and Upgrading Etherpad

⬆️ Updating Docker Images

For Docker deployments, update the image:


docker-compose pull

docker-compose up -d

πŸ› οΈ Manual Updates

For manual installations, pull the latest changes:


cd /path/to/etherpad

git pull origin master

npm install --legacy-peer-deps

npm start

πŸ” Checking for Updates

Subscribe to Etherpad’s GitHub repository to monitor new releases and changelogs.

Leveraging Etherpad’s Unique Features

πŸ”§ Enabling APIs

Edit settings.json to enable the Etherpad API:


"api": {

"enabled": true,

"apikey": "your_api_key"

}

Test the API with curl:


curl -X POST http://localhost:9001/api/1/createPad -d 'apikey=your_api_key&padID=testPad'

🌟 Advanced Configurations

Customize themes by editing settings.json:


"skinName": "colibris",

"skinVariants": "super-light-toolbar",

You can also install plugins to extend functionality:


npm install ep_webrtc ep_markdown

Restart Etherpad to enable plugins:


npm stop && npm start

Wrapping Up

In this guide, we’ve covered all the essential steps to deploy, configure, secure, back up, and customize Etherpad. By following these instructions, you can harness the power of Etherpad for collaborative editing while maintaining full control over your data. Dive into its API and plugins to further enhance its functionality for your team or organization.

Great! You’ve successfully signed up.
Welcome back! You've successfully signed in.
You've successfully subscribed to Selfhosted Ninja.
Your link has expired.
Success! Check your email for magic link to sign-in.
Success! Your billing info has been updated.
Your billing was not updated.