How to Self-Host Etherpad in 2026: Pads, Plugins and Database Backups

If you already tried to self-host Etherpad, the frustrating state is probably familiar: the UI appears, but sessions disconnect because proxy timeouts are too short. Recreating the container rarely fixes a disagreement between URLs, state and dependencies.

This walkthrough uses one concrete completion criterion — open one pad in two browsers, edit concurrently, inspect revisions and export the result in a required format. Every configuration choice is evaluated against that criterion rather than against a green container badge.

Choose the smallest viable Etherpad topology

The smallest responsible Etherpad topology contains one private listener on 9001, an ingress route and a documented state boundary. The network contract for Etherpad is Postgres or another supported database for durable multi-user use. Keep private endpoints on internal DNS, permit only required outbound calls and give Etherpad a scoped service credential.

Validate the topology by asking a clean client to open one pad in two browsers, edit concurrently, inspect revisions and export the result in a required format. Watch WebSocket sessions, revision count, database writes and plugin execution while it runs. The result tells you whether the next improvement belongs in memory, storage, networking or a separate worker instead of encouraging arbitrary container sizing.

Build a replaceable Etherpad container

Use the container as a replaceable runtime, not as the location of truth.

docker run -d \
  --name etherpad \
  --restart unless-stopped \
  -p 127.0.0.1:9001:9001 \
  -v etherpad-data:/opt/etherpad-lite/var \
  -e ADMIN_PASSWORD=replace-with-a-long-random-value \
  etherpad/etherpad:latest

Add the reviewed connection settings for Postgres or another supported database for durable multi-user use; use private names for private services. Inspect the container user, writable paths and bound listener before exposing it. Run the complete action — open one pad in two browsers, edit concurrently, inspect revisions and export the result in a required format — and save the exact image reference that produced the result.

Prevent proxy success from masking application failure

The browser, API client and Etherpad must agree on one origin. To make that true, set the public URL and proxy WebSocket support. Preserve the original host and protocol while keeping port 9001 unavailable as a competing public address.

The site-down troubleshooting guide helps distinguish an unreachable route from a responding application. That distinction matters here: sessions disconnect because proxy timeouts are too short. Only the former is fixed by ingress changes; the latter needs Etherpad logs, state or workload inspection.

Design the Etherpad restore before launch

Protect Etherpad's state before optimizing its container. The required set is database, uploaded plugins and settings. Mount /opt/etherpad-lite/var before bootstrap, write harmless sample data and replace the container to prove that path is actually persistent. If multiple stores must agree, document the order in which writes are paused and backups are taken.

Keep copies outside the deployment server and encrypt material containing credentials or private content. Recovery succeeds when pads, authors, revisions and plugins return and concurrent edits still converge. The distinction between a persistent mount and an independent copy is covered in persistent storage and snapshots.

Choose the Etherpad trust boundary

Close the bootstrap window as soon as the first trusted administrator exists. Etherpad's concrete trap is shipping a known admin password or leaving pads writable to everyone; the safer boundary is to set a real admin password, decide who may create pads and avoid assuming an obscure pad URL is private.

Replace the sample ADMIN_PASSWORD immediately, store it outside the image and rotate it like an administrator credential if it is exposed. Private networking should carry dependency credentials, and roles inside Etherpad should grant the smallest useful action. Keep sensitive request bodies and provider responses out of routine logs.

Upgrade Etherpad without guessing

Observe the work Etherpad performs: WebSocket sessions, revision count, database writes and plugin execution. Set limits with headroom for that work and avoid a liveness probe that competes with it. The operator check should still attempt to open one pad in two browsers, edit concurrently, inspect revisions and export the result in a required format on a schedule.

For updates, remember that Etherpad plugin versions, settings syntax and database migrations should be tested together. Deploy the candidate against a recovered copy and repeat the known test. If sessions disconnect because proxy timeouts are too short, use runtime logs and the actual network request to find which assumption changed.

What must pass before real Etherpad data arrives

For Etherpad, define a known-good transaction before launch: open one pad in two browsers, edit concurrently, inspect revisions and export the result in a required format. Put its prerequisites, expected response and cleanup steps in version control without secret values. Pin the image used to establish that reference.

Use the transaction to validate a replacement and an independent restore. The restored service is acceptable only when pads, authors, revisions and plugins return and concurrent edits still converge. At the same time, observe WebSocket sessions, revision count, database writes and plugin execution and turn the slowest or most constrained part into a service-level alert.

The gate also needs a negative case: temporarily deny the test identity access to Postgres or another supported database for durable multi-user use. Confirm that Etherpad produces an actionable error while preserving data, restore the valid condition and repeat the known-good transaction. Keeping both results prevents a superficial health endpoint from becoming the only production evidence.

Deploy Etherpad on Dockup without losing its boundaries

For Etherpad, Dockup is most useful at the boundary between an image and a durable service. It keeps the route to 9001, TLS, secret values and storage attached across container replacements, whether the compute belongs to Dockup or to your attached server.

Finish with application knowledge: set the public URL and proxy WebSocket support; connect and test Postgres or another supported database for durable multi-user use; and run this verification: open one pad in two browsers, edit concurrently, inspect revisions and export the result in a required format. Keep the result as a deployment check so the next image update is judged by behavior rather than by container status.

Frequently asked questions

What does Etherpad need for a production deployment?

Route the Etherpad container on port 9001 through one HTTPS origin. The supporting network requirement is Postgres or another supported database for durable multi-user use. Do not call Etherpad ready until you can open one pad in two browsers, edit concurrently, inspect revisions and export the result in a required format.

Which Etherpad data belongs in a backup?

Persist /opt/etherpad-lite/var and include database, uploaded plugins and settings in the same recovery manifest. A clean Etherpad restore passes only when pads, authors, revisions and plugins return and concurrent edits still converge.

Does Etherpad require HTTPS behind a reverse proxy?

Use HTTPS for the public Etherpad origin and keep port 9001 on the internal route. Apply the Etherpad setting correctly: set the public URL and proxy WebSocket support. For Etherpad, HTTPS protects credentials or user content in transit and keeps origin-sensitive client behavior consistent.

How should an Etherpad upgrade be tested?

Restore current Etherpad state into an isolated deployment, apply the candidate version and repeat its acceptance transaction. Pay particular attention because Etherpad plugin versions, settings syntax and database migrations should be tested together. Keep the previous Etherpad image until its data-migration and rollback boundary are understood.