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.
