How to Set Up Etherpad on Debian – A No‑Bloat, Hands‑On Guide
You’ll learn how to spin up a fresh, lean instance of Etherpad on a clean Debian machine, all with just a handful of commands and no fancy Docker wizardry. Skip the over‑engineered setups that come bundled with tons of unused dependencies.
1. Pick the Right Debian Version
Etherpad runs comfortably on any recent stable release—Buster, Bullseye, or Bookworm will do. I once watched a server on old Stretch crash every time it tried to load the latest Node.js, so start with at least Bullseye.
2. Install Node.js (v18 LTS)
Etherpad is built for Node, and the community recommends using the LTS branch. The Debian repos ship Node 14 by default, which will give you an error about “invalid engine” when you try to install Etherpad.
curl -fsSL https://deb.nodesource.com/setup_18.x | bash - apt-get install -y nodejs
Why this matters? Without the correct major version, the npm install step in Etherpad will abort. It’s a silent failure that leaves you staring at an empty error log.
3. Grab Etherpad from GitHub
Clone the repo to your home folder or /opt, whatever feels right:
git clone https://github.com/etherpad-lite/etherpad-lite.git ~/etherpad cd ~/etherpad npm install --production
Running npm install pulls in all JS dependencies. The --production flag skips dev‑only modules, saving you a few megabytes and time.
4. Configure the Server
Create a simple config file at settings.json. Copy the default first:
cp settings.json.example settings.json
Open it and tweak only what you need:
{
"server": {
"port": 9001,
"host": "0.0.0.0"
},
"databaseType": "sqlite",
"etherpadPath": "/opt/etherpad/"
}
Why not use PostgreSQL right away? SQLite is perfect for a single‑user or small‑team setup and avoids the extra service you’d have to maintain.
5. Run Etherpad (Development vs Production)
For quick testing, just launch it directly:
node .
You’ll see “Listening on port 9001” in the console. Open http://your-server:9001 and you’re live. When you’re ready to keep it running after a reboot, wrap it with a simple systemd service.
# /etc/systemd/system/etherpad.service [Unit] Description=Etherpad Lite After=network.target [Service] Type=simple User=www-data WorkingDirectory=/opt/etherpad ExecStart=/usr/bin/node . Restart=on-failure [Install] WantedBy=multi-user.target
systemctl daemon-reload systemctl enable --now etherpad.service
Why systemd? It gives you graceful restarts, automatic recovery, and a clean journalctl -u etherpad log.
6. Secure the Instance
If your Etherpad is exposed to the internet, set up HTTPS. The easiest way on Debian is Certbot with Nginx:
apt-get install certbot python3-certbot-nginx nginx
Configure a reverse proxy that forwards https://pad.yourdomain.com to http://localhost:9001. A minimal Nginx block looks like this:
server {
listen 443 ssl;
server_name pad.yourdomain.com;
ssl_certificate /etc/letsencrypt/live/pad.yourdomain.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/pad.yourdomain.com/privkey.pem;
location / {
proxy_pass http://localhost:9001;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
Run Certbot to get the certs, then reload Nginx. That’s all you need for a secure pad.
7. Keep Etherpad Updated
When the project releases a new version, pull the latest code and reinstall dependencies:
cd ~/etherpad git pull origin master npm install --production
Restart your systemd unit to apply changes:
systemctl restart etherpad.service
I’ve seen servers silently drift into breaking states after an unattended apt upgrade that bumps Node.js to a non‑compatible version. A quick check of the log and a rollback to 18.x fixes it fast.
Final Thoughts
That’s the whole recipe—no bloated containers, no unnecessary services, just a tidy Node app running on Debian. If you run into errors, the console output is usually self‑explanatory; you’re not buried in cryptic Docker logs. Happy padding!
