Etherpad is an open-source, web-based text editor that allows multiple users to edit the same document in real time. Each participant is assigned their own color, making it easy to track changes visually. It’s an ideal solution for collaborative work on notes, meeting minutes, or brainstorming sessions, offering instant synchronization and the ability to review edit history.

Prerequisites and Preparation

Before installing Etherpad, make sure your server meets the minimum requirements and is ready to work with Docker.

Updating Ubuntu

Before installing any new packages, it’s recommended to update the package list and upgrade installed packages to the latest versions. This ensures you’re using the most up-to-date software with security and stability fixes.

Run the following command:

sudo apt update && sudo apt upgrade -y

Creating the Etherpad Project Directory

It’s good practice to create a separate directory for each Docker Compose project. This helps keep files organized and isolated.

1. Create a directory for Etherpad:

mkdir -p ~/etherpad

Explanation:

• mkdir — creates a directory.
• -p — creates parent directories if they do not exist.
• ~/etherpad — the path to the new directory in your home folder.

2. Navigate to the directory:

cd ~/etherpad

Explanation: All further actions related to the docker-compose.yml file will be performed from this directory.

Creating the docker-compose.yml File for Etherpad

The docker-compose.yml file is the heart of your multi-container application. It defines all the services (containers), networks, and volumes required for Etherpad.

1. Create the docker-compose.yml file:

nano docker-compose.yml

2. Paste the following content:

services:
  etherpad:
    image: etherpad/etherpad:1.9.0
    ports:
      - "9001:9001"
    environment:
      # Built-in file-based DB (not for production)
      - DB_TYPE=sqlite
      - DB_PATH=/opt/etherpad-lite/var

      # Admin (optional)
      - ADMIN_USER=admin
      - ADMIN_PASSWORD=YOUR_ADMIN_PASSWORD

      # Basic settings
      - TITLE=Etherpad
      - TRUST_PROXY=true
    volumes:
      - etherpad_data:/opt/etherpad-lite/var
    restart: always

volumes:
  etherpad_data:

Save the file (Ctrl+O, Enter, Ctrl+X).

Configuring Etherpad via docker-compose.yml

Database Settings (SQLite)

By default, SQLite is used, which requires no additional configuration other than specifying the database file path:

- DB_TYPE=sqlite
- DB_PATH=/opt/etherpad-lite/var

Explanation:

• DB_TYPE=sqlite — tells Etherpad to use SQLite.
• DB_PATH — location of dirty.db inside the container (data is persisted via the named volume).

Starting Etherpad with Docker Compose

Make sure you are in the ~/etherpad directory containing your docker-compose.yml file, then run:

docker compose up -d

Verifying the Installation

Viewing Logs

docker compose logs -f etherpad

Checking Service Status

docker compose ps

Accessing Etherpad in the Browser

Open your browser and go to:

http://SERVER_IP:9001

Enabling Additional Features

Installing Etherpad Plugins

1. Go to: http://SERVER_IP:9001/admin
2. Log in using the YOUR_ADMIN_PASSWORD.
3. In the plugin management section, search for and install plugins.

Common Issues

Common Issues

Error / Symptom	Cause	Solution	Diagnostics (logs / commands)
Etherpad unavailable on port 9001	The container is not running or the port is in use.	Make sure the etherpad container is running. Check if port 9001 is occupied by another application on the host.	docker compose ps , docker logs etherpad , `sudo ss -tulpn
Domain access not working (Nginx)	Nginx configuration error, the domain does not point to the server, or Nginx was not restarted.	Check the Nginx configuration syntax, ensure domain records (A/AAAA) point to your server’s IP. Restart Nginx.	sudo nginx -t , sudo systemctl status nginx , dig YOUR_DOMAIN
Changes in settings.json not applied	The container was not restarted after editing the file.	Restart the Etherpad container: docker compose down && docker compose up -d .	docker logs etherpad (look for configuration load messages)
Errors when working with pads (e.g., saving)	Permission issues with the ./data directory or insufficient disk space.	Make sure the Docker user has write permissions to ~/etherpad/data. Check available disk space.	docker logs etherpad , df -h , ls -l ~/etherpad/data
Unable to install plugins via the web interface	Network access issues from the container or incorrect permissions.	Check the container’s network connectivity. Make sure Etherpad can access the plugin repository.	docker logs etherpad

Useful Links