Analytics cookies only (Google Analytics, PostHog). No ad networks, no cross-site tracking. See our privacy policy.
Updated Nov 2026
verified on Ubuntu 26.04 · Nov 2026Self-host Etherpad with Docker Compose and PostgreSQL on a small VPS — pinned image, generated secrets, TRUST_PROXY behind Caddy HTTPS, and pads locked behind a login.
Etherpad is a real-time collaborative editor for plain
documents. People open a pad by its URL and type together, each author's text
is shown in their own colour, and every pad keeps a revision history. It is
Apache-2.0 licensed, a TypeScript and Node.js application, and the
official Docker route runs one etherpad/etherpad image beside PostgreSQL. It
is rated 2 / 5 to deploy.
It is a document editor rather than an office suite: there are no spreadsheets or slides. If you need those, look at OnlyOffice (with its deploy guide) or Nextcloud; for collaborative Markdown notes see HedgeDoc. If you are replacing a hosted product, see Google Workspace alternatives.
Etherpad is open by default. Out of the box, anyone who can reach the URL
can open any pad by guessing its name, and can create a new pad just by
visiting a new name. Upstream's metrics endpoint is public by default
too. This guide closes both: it turns on upstream's
requireAuthentication setting, so every pad needs a username and password,
and it turns off the metrics endpoint. If you want the open, anyone-can-use-it
behaviour, see the end of the first-run section.
Upstream's README lists no RAM or disk requirement for the Docker image (it gives Node.js 24 or newer as the requirement for running from source).
In our install check (GCP e2-standard-2, Ubuntu 26.04, November 2026) the
stack of Etherpad, PostgreSQL and Caddy idled at about 250 MB of RAM
(Etherpad about 204 MB, PostgreSQL about 30 MB, Caddy about 14 MB), measured
with docker stats --no-stream about three minutes after a fresh start with
no pads open, and about 1.4 GB of Docker disk (docker system df). Memory grows with the number of
pads people have open at once, so give a busy instance headroom.
Install Docker and the Compose plugin by following Docker and Compose on Ubuntu, and confirm the versions:
docker --version
docker compose version
Open SSH plus the two ports Caddy will use. Etherpad itself gets no public port:
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw --force enable
Docker publishes container ports by editing the firewall directly, which
bypasses ufw rules. That is why the compose file below binds Etherpad's port
to 127.0.0.1.
Paid link — we earn a commission if you shop through it.
Generate the three secrets first: the database password, the password for
Etherpad's admin user, and the password for the ordinary user account that
people will share. The block only writes .env if it does not exist, so
re-running it cannot rotate the passwords under a live database (PostgreSQL
only reads its password on first start):
mkdir -p ~/etherpad && cd ~/etherpad
[ -f .env ] || cat > .env <<EOF
DB_PASSWORD=$(openssl rand -hex 16)
ADMIN_PASSWORD=$(openssl rand -hex 16)
USER_PASSWORD=$(openssl rand -hex 16)
EOF
chmod 600 .env
The compose file is upstream's PostgreSQL example reduced to what is needed,
with the version pinned to 3.3.16 instead of latest. 3.3.16 matters: GitHub's advisory GHSA-c36r-65p6-q3m9 (rated high) describes a cross-pad race that exposes chat and revision history of pads a user is not authorized for, and 3.3.16 is the release that fixes it. Upstream's
settings.json reads its values from environment variables, so everything is
configured here and you never edit the settings file. That matters: upstream's
compose file warns that settings edited through the admin UI live in the
container's writable layer and are reverted by docker compose down && up
or an image pull, unless you mount your own settings.json.
cd ~/etherpad
cat > docker-compose.yml <<'EOF'
services:
etherpad:
image: etherpad/etherpad:3.3.16
user: "5001:0"
restart: unless-stopped
ports:
- "127.0.0.1:9001:9001"
environment:
NODE_ENV: production
ADMIN_PASSWORD: ${ADMIN_PASSWORD}
USER_PASSWORD: ${USER_PASSWORD}
REQUIRE_AUTHENTICATION: "true"
ENABLE_METRICS: "false"
TRUST_PROXY: "true"
DB_TYPE: postgres
DB_HOST: db
DB_PORT: 5432
DB_NAME: etherpad
DB_USER: etherpad
DB_PASS: ${DB_PASSWORD}
DEFAULT_PAD_TEXT: " "
volumes:
- plugins:/opt/etherpad-lite/src/plugin_packages
- etherpad_var:/opt/etherpad-lite/var
depends_on:
db:
condition: service_healthy
db:
image: postgres:15-alpine
restart: unless-stopped
environment:
POSTGRES_DB: etherpad
POSTGRES_USER: etherpad
POSTGRES_PASSWORD: ${DB_PASSWORD}
PGDATA: /var/lib/postgresql/data/pgdata
healthcheck:
test: ["CMD-SHELL", "pg_isready -U etherpad -d etherpad"]
interval: 3s
timeout: 3s
retries: 20
volumes:
- db_data:/var/lib/postgresql/data
volumes:
plugins:
etherpad_var:
db_data:
EOF
What the settings do, each read from upstream's settings.json.docker at
3.3.16:
ADMIN_PASSWORD creates the admin user, who is the only one allowed
into the /admin pages. Upstream notes that a user whose password is null is
simply not created, so without it there is no admin at all.USER_PASSWORD creates a second, non-admin user named user.REQUIRE_AUTHENTICATION defaults to false. Set to true, pad and
admin requests need a login from the users list (a few non-pad endpoints
stay public, see first-run setup), which is how this guide locks
down pad access.ENABLE_METRICS defaults to true, which serves Etherpad's internal
statistics at /stats/ and a Prometheus format at /stats/prometheus to
anyone who asks; we measured both answering 200 without a login on a
default install and 404 once it was false. It is for monitoring plugins,
so turn it off unless you use one.TRUST_PROXY is covered below.DEFAULT_PAD_TEXT: " " replaces the long welcome text new pads start
with.Start the stack. The first start creates the database tables, and Etherpad
logs Etherpad is running when it is ready:
cd ~/etherpad
docker compose up -d
set -a; . ./.env; set +a
out=000
for i in $(seq 1 60); do
out=$(curl -s -o /dev/null -w '%{http_code}' -u "user:$USER_PASSWORD" http://127.0.0.1:9001/)
[ "$out" = "200" ] && break
sleep 3
done
docker compose ps
echo "loopback check as user: $out"
[ "$out" = "200" ] || false
Create an A record for your hostname (say pad.example.com) pointing at
the server. With no domain yet, an sslip.io name resolves to your server's
IP with no DNS setup, which is what this guide uses so every command runs as
written:
DOMAIN="etherpad.$(curl -4s https://ifconfig.me).sslip.io"
echo "$DOMAIN"
Keep this shell session open (or re-run the line) for the rest of the guide, and replace the value with your real hostname when you have one.
Run Caddy as a container on the host network. It obtains and renews a Let's
Encrypt certificate on its own (see
Automatic HTTPS with Caddy) and proxies
to the loopback port. reverse_proxy supports WebSocket upgrades without extra
configuration, which Etherpad's live editing needs:
mkdir -p ~/caddy
cat > ~/caddy/Caddyfile <<EOF
$DOMAIN {
reverse_proxy 127.0.0.1:9001
}
EOF
docker rm -f caddy >/dev/null 2>&1 || true
docker run -d --name caddy --restart unless-stopped --network host \
-v ~/caddy/Caddyfile:/etc/caddy/Caddyfile:ro -v caddy_data:/data caddy:2
TRUST_PROXY is trueUpstream's setting comment says: "When you use NGINX or another
proxy/load-balancer set this to true. This is especially necessary when the
reverse proxy performs SSL termination, otherwise the cookies will not have
the 'secure' flag." Its default is false, which is right for exposing the
port directly and wrong behind Caddy, which terminates TLS.
We checked it on this stack. With TRUST_PROXY=false behind Caddy, the
token cookie Etherpad issues was HttpOnly; SameSite=Lax. With
TRUST_PROXY=true it gained Secure. Because the container port is bound to
loopback, only Caddy can reach it, so trusting its forwarded headers is safe;
never set it to true on an instance whose port is exposed directly.
Now check the whole path. The first block waits for the certificate, then
confirms the login is enforced and the cookie is Secure. The second opens a
real pad over a websocket through Caddy, using the Socket.IO client that ships
inside the Etherpad image, and expects the server to answer with the pad's
state (CLIENT_VARS), which only happens when the websocket upgrade works:
cd ~/etherpad
set -a; . ./.env; set +a
out=000
for i in $(seq 1 24); do
out=$(curl -s -o /dev/null -w '%{http_code} %{ssl_verify_result}' -u "user:$USER_PASSWORD" "https://$DOMAIN/") && [ "${out%% *}" = "200" ] && break
sleep 5
done
echo "as user, HTTPS and certificate check: $out"
[ "${out%% *}" = "200" ] || false
anon=$(curl -s -o /dev/null -w '%{http_code}' "https://$DOMAIN/p/notes")
echo "no login: $anon"
[ "$anon" = "401" ] || false
curl -s -D - -o /dev/null -u "user:$USER_PASSWORD" "https://$DOMAIN/p/notes" | grep -i '^set-cookie: token=' | grep -q 'Secure' && echo "token cookie is Secure"
cd ~/etherpad
set -a; . ./.env; set +a
docker compose exec -T -e DOMAIN="$DOMAIN" -e AUTH="user:$USER_PASSWORD" etherpad sh -c 'cd /opt/etherpad-lite/src && node -' <<'JS'
const { io } = require("socket.io-client");
const base = "https://" + process.env.DOMAIN;
const pad = "ws-check-" + Date.now();
const auth = { Authorization: "Basic " + Buffer.from(process.env.AUTH).toString("base64") };
(async () => {
const page = await fetch(base + "/p/" + pad, { headers: auth });
if (page.status !== 200) { console.log("page status " + page.status); process.exit(2); }
const cookie = page.headers.getSetCookie().map((c) => c.split(";")[0]).join("; ");
const s = io(base, { transports: ["websocket"], reconnection: false, extraHeaders: { ...auth, Cookie: cookie } });
const bye = (m, c) => { console.log(m); s.close(); process.exit(c); };
s.on("connect_error", (e) => bye("connect_error: " + e.message, 1));
s.on("connect", () => s.emit("message", { component: "pad", type: "CLIENT_READY", padId: pad, sessionID: null, userInfo: {}, protocolVersion: 2 }));
s.on("message", (m) => bye(m.type === "CLIENT_VARS" ? "websocket works: CLIENT_VARS for pad " + m.data.padId : "unexpected: " + JSON.stringify(m).slice(0, 200), m.type === "CLIENT_VARS" ? 0 : 2));
setTimeout(() => bye("timeout", 3), 10000);
})();
JS
A second number of 0 on the first check means the certificate verified.
There is no setup wizard and nothing to claim first: the accounts exist from
the first start, and every pad and admin page is behind the login (a few
non-pad endpoints stay public: we saw 200 without a login on /health,
/api, /locales.json, /pluginfw/plugin-definitions.json, /manifest.json,
/robots.txt and the Socket.IO handshake). Open
https://pad.example.com (your hostname), sign in as user with the
USER_PASSWORD from .env, and open a pad by name, for example /p/notes.
Share that password (and the pad URL) with the people who should collaborate.
Print it with grep '^USER_PASSWORD=' ~/etherpad/.env.
The administration pages are at /admin, reached as admin with
ADMIN_PASSWORD. We checked the gate on /admin-auth/: 401 with no login,
403 for user, 200 for admin.
cd ~/etherpad
set -a; . ./.env; set +a
echo "none: $(curl -s -o /dev/null -w '%{http_code}' "https://$DOMAIN/admin-auth/")"
echo "user: $(curl -s -o /dev/null -w '%{http_code}' -u "user:$USER_PASSWORD" "https://$DOMAIN/admin-auth/")"
echo "admin: $(curl -s -o /dev/null -w '%{http_code}' -u "admin:$ADMIN_PASSWORD" "https://$DOMAIN/admin-auth/")"
From /admin you manage plugins and view settings. Plugins install into the
plugins volume, so they survive upgrades.
A few behaviours worth knowing, all from upstream's settings file at this
version. Pads can only be deleted by the original creator's author cookie or by
the one-time deletion token shown to the creator, unless
ALLOW_PAD_DELETION_BY_ALL_USERS is true. The users list in settings.json also supports readOnly and
canCreate per user, but the image only maps passwords from environment
variables, so using them means mounting your own settings.json. Upstream
warns that passwords there are stored in plaintext and points to the
ep_hash_auth plugin to mitigate that.
If you want it open instead, delete the REQUIRE_AUTHENTICATION and
USER_PASSWORD lines from the compose file and run docker compose up -d.
Then anyone with the URL can read and write any pad they can name, so pick
this only for a public scratchpad and consider the pad names your only
secret. Leave ADMIN_PASSWORD set either way; /admin always requires a login.
Four things need protecting:
store
table). A pg_dump is the portable copy..env, which holds the passwords you will need again to restore.docker-compose.yml, which pins the version and settings.var/installed_plugins.json, the list of installed plugins, which lives
in the etherpad_var volume that nothing else here captures.Dump the database with the stack running:
cd ~/etherpad
mkdir -p ~/etherpad-backup
docker compose exec -T db pg_dump -U etherpad etherpad | gzip > ~/etherpad-backup/etherpad-$(date +%F).sql.gz
docker compose cp etherpad:/opt/etherpad-lite/var/installed_plugins.json ~/etherpad-backup/
tar czf ~/etherpad-backup/etherpad-config-$(date +%F).tgz .env docker-compose.yml
ls -lh ~/etherpad-backup
Copy the archives off the server on a schedule. To restore on a server with
the same .env and compose file, start only the database first, load the
dump, and only then start Etherpad. If Etherpad starts first it creates its own
rows in the store table and the dump hits duplicate keys. Replace the date
with your archive's:
cd ~/etherpad
docker compose down -v # only on the server you are restoring INTO
docker compose up -d db
until docker compose exec -T db pg_isready -U etherpad -d etherpad; do sleep 2; done
gunzip -c ~/etherpad-backup/etherpad-2026-11-08.sql.gz | docker compose exec -T db psql -q -v ON_ERROR_STOP=1 -U etherpad -d etherpad
docker compose up -d
We tested this on the verification server: with a pad created from imported
text, we backed up, wiped the volumes, restored in this order and the pad's
text came back unchanged, with no duplicate-key errors in the logs. The plugin
list is only a record: reinstall those plugins from /admin afterwards. An
untested backup is a guess, so restore into a throwaway server now and then.
By default the container checks the GitHub Releases API every six hours and
shows an update banner; upstream says Docker installs are read-only and never
apply an update themselves. A second, separate check polls etherpad.org hourly
for the admin panel's update notice (PRIVACY.md). To stop both outbound
checks, add UPDATES_TIER: "off" and PRIVACY_UPDATE_CHECK: "false" to the
etherpad service's environment; settings.json.docker maps both variables. To upgrade, take the backup above,
read the release notes on the project's GitHub releases page, change the
image tag, pull and recreate. Settings come from the environment, so nothing is
lost when the container is recreated.
cd ~/etherpad
sed -i 's|etherpad/etherpad:3.3.16|etherpad/etherpad:NEW_VERSION|' docker-compose.yml
docker compose pull etherpad
docker compose up -d etherpad
docker compose logs --tail 30 etherpad
The PostgreSQL tag is a separate decision. A major PostgreSQL upgrade needs a
dump and restore, not just a new image; postgres:15-alpine follows that
major only.
Every pad page returns 401. That is the login doing its job: browsers will
prompt for a username and password. Use user and the USER_PASSWORD from
.env. If you changed .env after the first start, recreate the container
(docker compose up -d) so it reads the new value.
The pad page loads but stays on "reconnecting". Websockets are not getting
through. Re-run the websocket check above. If you put a different proxy in
front of Etherpad, it must upgrade connections for /socket.io/.
The token cookie is missing Secure. TRUST_PROXY is false. Set it to true as shown (and only
behind a proxy), then docker compose up -d.
Etherpad cannot reach the database on first start. The etherpad service
waits for the database healthcheck. If PostgreSQL started with a different
password than the current DB_PASSWORD in .env, it will not match, because
the password is only applied when the database is first created. Check
docker compose logs db etherpad.
Port 9001 is reachable from the internet. The port line lost its
127.0.0.1: prefix. Fix the compose file, docker compose up -d, then check
that ss -tln | grep 9001 shows 127.0.0.1. Do this before anything else if
you also set TRUST_PROXY to true.
Certificate never issues. That is a Caddy and DNS problem rather than an
Etherpad one: confirm the A record resolves (dig +short pad.example.com) and
that ports 80 and 443 are reachable. Look at docker logs caddy.
You are done when https://pad.example.com asks for a login, accepts user
with a valid certificate, a pad opens and syncs live, port 9001 is bound only to
127.0.0.1, and a database dump plus .env are landing off the server.
Confirm the port binding and that nothing is restarting:
sudo ss -tlnp | grep ':9001 '
docker compose -f ~/etherpad/docker-compose.yml ps
From here, share the pad URL and the user password with your collaborators,
and browse the plugins in /admin for what your team needs. If you outgrow
plain-text documents, see OnlyOffice and
Nextcloud.
We estimate about 25 minutes of hands-on time for "How to Deploy Etherpad on a VPS"; this is an editorial estimate, not a measurement.
The "How to Deploy Etherpad on a VPS" guide was verified end-to-end on Ubuntu 26.04 (Nov 2026).