Hardware FixRecommendedDevice not working? Your driver may be the problemCheck updates for common hardware issues.Fix DriversHalloween DealsAmazon USHalloween week deals: useful picks before month-endAmazon US: current deals, useful picks and tech finds.Check DealsClean PCRecommendedOne scan can reveal what keeps slowing WindowsLook for cleanup and repair opportunities.Run Scan×
FREEDOM251

Freedom251 › Blog › Caddy

How to Self-Host Etherpad on a VPS in 2026

By Freedom251 Team · · 10 min read

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Run Etherpad privately on port 9001, then publish it through a reverse proxy on ports 80 and 443. This layout keeps the editor off the public network, provides HTTPS, preserves WebSocket connections for real-time editing, and gives you one place to manage certificates and access rules. You can deploy the application with the official Docker image or install it from source; either approach needs persistent data, a database plan, backups, and a tested update procedure.

What a production Etherpad VPS looks like

The reliable topology is:

Internet → firewall (80/443) → reverse proxy → Etherpad on 127.0.0.1:9001

As an Amazon Associate I earn from qualifying purchases.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Etherpad normally listens on TCP port 9001. Bind that port to the VPS loopback address instead of exposing it directly to the Internet. The reverse proxy receives requests for your public hostname, terminates TLS, and forwards them to http://127.0.0.1:9001. This is the production pattern described in Etherpad’s deployment documentation.

  • Allow inbound TCP 80 and 443 in the VPS firewall so HTTP validation and HTTPS traffic can reach the proxy.
  • Do not publish the Etherpad or database ports to the public network.
  • Point a DNS name such as pad.example.com at the VPS address before requesting a certificate.
  • Forward WebSocket upgrade requests; otherwise collaboration can fall back to slow long-polling or fail.

Choose Docker or a source installation

Decision Official Docker image Source installation
Repeatable deployment Pin an image tag and recreate the container when changing versions. Pin the Etherpad release and Node.js dependencies yourself.
Configuration Most settings are supplied as environment variables. Settings are maintained in the installation’s configuration files.
Plugin and runtime control Convenient, but you work within the image’s runtime and build process. More direct control over plugins, Node dependencies, and local changes.
Rollback Re-deploy the previously tested image tag. Restore the prior source revision and dependency set.
Operations Container logs and compose or Docker commands provide a reproducible workflow. You must define how the process starts, restarts, logs, and upgrades.

Docker is usually the shortest path for a new VPS because the application runtime is packaged. A source install is reasonable when you need custom plugin development, a nonstandard build, or tighter control over dependencies. Do not choose based only on the initial install: your database backups, uploaded files, plugin-managed files, and rollback process matter more after the first day.

#1 Best Overall
Sale
TOZO A1 Wireless Earbuds Bluetooth 5.3 Light Weight in Ear Headphones | IPX5 Waterproof,2 Mics for AI Calls,Immersive Premium Sound Bass Headset with Charging Case,32 EQ via App Black
  • [Ultra-Lightweight Ear Buds Designed for Small Ears] Each earbud weighs only 3.7g and features a compact, ergonomic in-ear design made especially for small ears. Secure, low-profile, and comfortable for workouts, all-day wear or overnight sleeping.The ultra-slim profile sits flush in your ear with no hard edges poking or rubbing, so you can even sleep on your side without discomfort.
  • [Immersive Stereo Sound with TOZO OrigX Technology] TOZO OrigX tuning delivers clear vocals, balanced mids, and natural stereo sound for music, podcasts, and videos.
  • [Long Battery Life for Daily Use] Get up to 7 hours of playtime on a single charge, with up to 32 hours total using the charging case—ideal for workdays, commuting, and extended listening sessions.
  • [Bluetooth 5.3 & Stable Connection] Bluetooth 5.3 provides fast pairing, stable wireless performance, and reduced dropouts as you move around home or office.
  • [Deep Bass with Clear Vocals] High-performance drivers produce punchy bass while keeping vocals clean and detailed for everyday listening.

Prepare the VPS before installing Etherpad

1. Use a supported Linux account and hostname

Create a non-root administrator account, apply operating-system updates, and use SSH keys where your provider supports them. Set a fully qualified hostname in DNS, for example pad.example.com, and wait for it to resolve to the VPS before enabling public HTTPS.

2. Configure the firewall

  • Permit SSH only from the addresses or VPN through which you administer the server.
  • Permit TCP 80 and 443 to the reverse proxy.
  • Keep TCP 9001 closed externally; Etherpad should receive traffic from the proxy over loopback.
  • Keep database ports closed externally as well. Etherpad’s database connection should stay on a private interface or an internal network.

3. Decide where data and secrets live

Before starting the service, identify persistent storage for the database and for uploaded or plugin-managed files. A container’s writable layer is not a backup. Store administrator credentials and database passwords in protected environment files, a secret manager, or your service manager’s secret mechanism. Restrict permissions so ordinary users cannot read them.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Install Etherpad with Docker

Use an official image and a pinned tag

The official image is published as etherpad/etherpad on Docker Hub and mirrored as ghcr.io/ether/etherpad. The Docker documentation displays tag 2.6.1; verify the current release before deploying because tags change. Pin a known tag in production rather than relying on an unqualified floating tag.

Run a local-only test container

A minimal test command from the Docker documentation is:

docker run --detach --publish <DESIRED_PORT>:9001 <YOUR_USERNAME>/etherpad

The FAQ also shows:

docker run -p 9001:9001 etherpad/etherpad

For a VPS that already has a proxy, bind the host side to loopback so the editor is not directly reachable:

Rank #2
Sale
Smart Watch for Men Women Compatible with iPhone Samsung Android Phone 1.69 inch Full Touch Screen IP68 Waterproof Bluetooh Fitness Tracker Heart Rate/Sleep Monitor (Black)
  • 【IP68 Waterproof Multifunctinal Smart Watch】Torjalph fitness activity tracker smart watch is IP68 waterproof technology ,you can wear it when swimming,handwashing,it's rain-proof which means that you perform multiple exercise modes outside without worrying about sweat or rain corroding your fitness smart watch,and this watch equipped with a 230 mAh large capacity battery magnetic charging ,and this sports activity tracker watch can be used 5-7 days If fully charged.
  • 【Larger 1.83'' Full Screen Watch & Multi-dial Selection】1.83 inch full HD color touch screen smart watch for men / women provides excellent 240*284 resolution image quality ,This Bluetooth smart watch offers a better touch experience and remarkable immersion and ,more than 200 watch faces for you to choose from App"Da Fit ", you can change the dial style according to your mood to wear keeping the world on your wrist
  • 【Accurate Activity Tracker Smart Watch 】sports watch activity tracker uses sweat and dust resistant breathable silicone strap, our Fitness Tracker Smart Watch for Android iOS Phones supports 12 sports modes,walking,running,bicycle,swimming,badminton,basketball,football,rope skipping. This bluetooth calls smart watch for men women is lightweight and stylish, bringing more convenient and relaxing sports experience while also providing more protection.
  • 【Your 24 Hour Personal Daily Health Monitor】Fitness watch for women men full touch screen IP67 waterproof bluetooth smartwatch for Android iOS Phones with heart rate blood pressure monitor multifunction Andriod smart watch with steps counter sleep monitor sports fitness watch, monitoring blood oxygen saturation allows you to understand your physical condition in real time to track fitness progress ,to know your health status in time.
  • 【More Functions Bluetooth Call Smart Watch】This fitness activity smart watch full screen for iPhone and Android phones includes a bunch of new features including:The bluetooth smart watch can hang up the phone, receive and display WhatsAPP /Text /Facebook /Twitter /Messenger reminder.Support sedentary reminder, alarm clock, stopwatch, timer,weather information,music control, remote camera control compatible with Android 5.0 and above or iOS 9.0 and above smartphones.
docker run --detach --name etherpad 
  --publish 127.0.0.1:9001:9001 
  etherpad/etherpad:2.6.1

Open the editor through the proxy hostname, not through the VPS address and port 9001. If you are only testing locally, temporarily publishing port 9001 is acceptable, but remove that exposure before production.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Set the important environment variables

The image reads most settings from environment variables. The key names are:

  • PORT (defaults to 9001)
  • DB_TYPE, DB_HOST, DB_PORT, DB_NAME, DB_USER, and DB_PASS
  • TRUST_PROXY

Configuration-variable substitution happens when Etherpad loads its configuration; it does not rewrite settings.json on disk. Treat an environment file as a secret: keep it outside public web directories, set restrictive permissions, and do not commit it to source control.

Choose a database deliberately

The image documents DirtyDB as the default fallback and lists SQLite as another file-backed option. Those defaults are useful for evaluation, but production data deserves a deliberate database choice and a tested restore procedure. If the database is on another private host, allow only the Etherpad server to reach its database port and use encrypted transport when your database setup supports it.

Mount persistent storage using the directory and volume guidance for the exact image tag you deploy. Keep the database, uploaded assets, and plugin-managed files in your backup scope. Test that a newly created pad survives container recreation before inviting users.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Rank #3
New Bee Guitar Cable 10ft Electric Instrument Bass AMP Cord
  • [Low Noise High Fidelity] New bee guitar cord with 22AWG oxygen-free-copper center conductors provides enhanced signal transfer, the PVC insulation material and the high-density stranded copper double shield provide noise rejection for quiet operation
  • [Ideal for Choice] New bee 1/4 straight and right angle metal connectors, ensures a secure connection in any instrument, pedal, or amp jack. L shape great fro on stage guitar stands
  • [Wide Compatible] Suitable for mixer, power amplifier, microphone, effector, decoder, equalizer, electoronic organ, electric guitar, electric bass and other electronic equipments. Widely used in the installation of smart home, karaoke speaker, professional stage audio, etc
  • [Easy Disassemble] Making incidental repairs quick and easy! Very nice, flexible cable
  • [Dont Hesite to Order] 24 hours customer services and professional technology team are standing by

Install Etherpad from source

Use the documented convenience installer carefully

The Etherpad FAQ documents this one-line Linux, macOS, and WSL installer:

curl -fsSL https://raw.githubusercontent.com/ether/etherpad/master/bin/installer.sh | sh

Piping a remote script directly to a shell is convenient, but it gives the downloaded script execution privileges. For a production VPS, download it first, inspect what it will install and change, confirm the revision or release policy you intend to use, and then run it as the appropriate non-root account. Pin the Etherpad release and Node.js dependency set rather than silently tracking a moving branch.

Make the source process a service

After installation, run Etherpad under a service manager that can restart it after a crash and start it after a reboot. Keep its listening address on 127.0.0.1 and its port at 9001 unless you have a specific reason to change them. Send logs to a location with rotation and monitoring; do not rely on an interactive SSH session.

Source deployments need an explicit upgrade recipe: record the checked-out revision, dependency installation command, plugin versions, configuration files, service definition, and rollback revision. Back up data before changing the application or dependencies.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Put NGINX, Caddy, or Traefik in front

Caddy: the smallest configuration

Caddy’s documented Etherpad example is:

pad.example.com {
    reverse_proxy 127.0.0.1:9001
}

Caddy handles WebSocket proxying and certificate issuance automatically in this pattern. Confirm that DNS already points to the VPS and that ports 80 and 443 are reachable so certificate validation can complete.

Rank #4
BSIMB 15.6" Digital Family Calendar & Chore Chart, No Subscription Fees
  • Digital Family Calendar: BSIMB digital calendar wall touch screen puts an end to your chaotic life. Designed for busy families, the digital calendar keeps you organised and in step with your family. Assign different colours and tasks to each family member to make family scheduling easier and more intuitive.
  • Easy Setup and Auto-Sync: Plug in, connect to WLAN and auto-syn your electric calendar in minutes. Digital wall calendar compatible with Google calendar, iCloud calendar, Outlook calendar, Cozi calendar and Yahoo calendar. Add events directly on the device or through the ecalendar app. Electronic calendar stays current whether you're at work or traveling—no manual updates needed.
  • All-In-One Home Assistant: Smart calendar builds habits and encourage independence with personalised chores. Display daily meal plan to reduce the daily ‘What's for dinner?’ stress. To-do lists keep track of everything you want. Turning chores into valuable achievements with stars and rewards, making life easier and more enjoyable.
  • Manage Anytime Anywhere: BSIMB electronic calendar for family stay connected with the powerful ecalendar app. Access and manage your digital wall calendar anytime, anywhere with free features like stars & rewards, photo screensaver, chore charts, meals plans, to-do lists etc. Electronic planner paid features like Magic Import tailor advanced tools for users with special needs.
  • Stay in Touch with Loved Ones: Share photos or videos from your phone to electronic wall calendar with app, instantly update your life moment, and keep in touch with your family, especially those who are far away; you can also surprise your smart calendar digital wall by sending him a wish card; it's also great for keeping tech-illiterate elders in touch with the youngsters.

NGINX: forward the WebSocket upgrade

With NGINX, proxy the public hostname to http://127.0.0.1:9001 and explicitly pass the WebSocket headers. A minimal server block has the following shape:

server {
    listen 80;
    server_name pad.example.com;

    location / {
        proxy_pass http://127.0.0.1:9001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Use your normal certificate-management method to add the HTTPS listener, then redirect HTTP to HTTPS. The essential behavior is not the spelling of the proxy product; it is preserving the upgrade and connection headers and passing the forwarded request information.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Traefik: fit it to an existing container or cluster stack

Traefik is a practical choice when your VPS already uses Docker labels or a Kubernetes ingress workflow. Define a router for the Etherpad hostname and a service targeting the container’s port 9001, then enable your existing certificate resolver. Verify the generated route passes WebSockets; do not assume that a route which serves the login page is also carrying collaborative editing traffic correctly.

Compare the proxy choices

Proxy Certificate handling WebSocket behavior Best fit
Caddy Automatic certificate issuance in the documented example. Handled by the reverse-proxy configuration shown. A single VPS where you want minimal configuration.
NGINX Use your chosen certificate automation or install certificates manually. Requires explicit upgrade and connection forwarding. Operators who already standardize on NGINX and need detailed request control.
Traefik Certificate automation is integrated with its resolver model. Configure and test the route in the same way as any other WebSocket service. Existing Docker or Kubernetes environments with dynamic routing.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Enable HTTPS and trust the proxy

Recommended: terminate TLS at the proxy

Let the reverse proxy handle the public certificate and send HTTP to Etherpad over loopback. In Etherpad, set trustProxy: true when the proxy terminates TLS. This allows Etherpad to trust X-Forwarded-* headers, record the client address correctly, and mark cookies as secure. Only enable this when Etherpad is reachable through a proxy you control; do not trust arbitrary forwarded headers from an exposed application port.

Alternative: native Etherpad HTTPS

Etherpad can also serve HTTPS itself. Add an ssl block to settings.json containing the private-key path, certificate path, and, when needed, an intermediate CA path. Restart Etherpad after editing. Native TLS can be useful when no reverse proxy is available, but the proxy-termination pattern keeps certificate renewal, redirects, and virtual-host routing in one place.

Hosting Etherpad under a path

If the public URL is a subpath such as https://example.com/pad rather than a dedicated hostname, configure the proxy to send X-Proxy-Path. Without that header, Etherpad can generate incorrect asset and API URLs. A dedicated hostname is usually simpler, but a subpath works when the proxy is configured consistently.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Persistence, backups, and recovery

What to back up

  • The complete Etherpad database, not only configuration files.
  • Uploaded assets and files created or managed by plugins.
  • Environment files, service definitions, proxy configuration, and certificate-renewal settings.
  • The exact Docker image tag or source revision used for the deployment.

Make backups restorable

Keep backups away from the VPS and encrypt them when they contain private pads. Record when each backup was made and how long it is retained. A backup is not proven until you restore it into an isolated test instance, start Etherpad with the same compatible application version, and confirm that existing pads open correctly.

Plan for a failed disk or container

If a container disappears, recreate it from the pinned image, reconnect the persistent storage, restore the database if necessary, and reapply the proxy settings. If the proxy fails, Etherpad may still be healthy on 127.0.0.1:9001; check each layer separately instead of changing the application configuration first.

Update Etherpad without losing pads

  1. Read the current Etherpad release notices and identify the target version or image tag.
  2. Export or snapshot the database and copy uploaded and plugin-managed files.
  3. Record the running image digest or source revision so you can return to it.
  4. Deploy the new image or source revision in a test or maintenance window.
  5. Check application logs, the proxy route, certificate status, and WebSocket negotiation.
  6. Create a new pad, open it in a second browser, edit from both sessions, and reconnect after briefly interrupting one network connection.
  7. Keep the previous image or source revision available until the new deployment has passed those checks.

The admin interface can notify you when a newer release is available. Docker-based updates use the documented pull and compose-update workflow, but an update is not complete until the data restore and collaboration tests succeed.

Troubleshoot the failures that matter

The page loads but edits do not appear in real time

Inspect the browser network panel and proxy logs for a WebSocket connection. Confirm that the proxy sends both Upgrade and Connection headers and that it uses HTTP/1.1 to the upstream. A page that renders successfully can still be using slow long-polling if the upgrade is missing.

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

The proxy returns 502 or connection refused

  • Check that the Etherpad process or container is running.
  • Confirm it listens on 127.0.0.1:9001, not on a different port set by PORT.
  • From the VPS, test the upstream locally; do not test only the public hostname.
  • Check whether the container was published to loopback on the host and whether the proxy runs in a separate network that needs a different upstream address.

Cookies, client addresses, or redirects are wrong

When TLS ends at the proxy, set trustProxy: true and pass the X-Forwarded-Proto, X-Forwarded-For, and host headers. Remove stale cookies after changing HTTP to HTTPS and verify that the proxy is not creating a redirect loop.

Assets or API calls break under /pad

Send X-Proxy-Path from the proxy and check that the externally visible path matches the path used by the browser. A dedicated hostname avoids this class of path-rewriting error.

Pads disappear after a restart

Check whether the database and application files are on persistent storage rather than the container’s temporary writable layer. Confirm the configured DB_TYPE and database connection variables, then restore a known backup in a separate instance before changing the live data.

Production hardening checklist

  • Use a dedicated DNS name and HTTPS for every user-facing instance.
  • Expose only ports 80 and 443 publicly; keep 9001 and database ports private.
  • Set trustProxy: true only behind your controlled proxy.
  • Use a protected secret store or environment file for administrator and database credentials.
  • Pin the Docker image tag or source revision.
  • Back up the database and plugin-managed files on a schedule and test restoration.
  • Monitor process health, disk space, database errors, certificate renewal, and proxy logs.
  • After every proxy or Etherpad change, test a new pad, two-browser editing, and reconnection after a network interruption.

A practical first-day deployment sequence

  1. Register or choose a hostname and point its DNS record at the VPS.
  2. Update the Linux system, create an administrator account, and restrict SSH.
  3. Open firewall ports 80 and 443; leave 9001 and database ports closed to the Internet.
  4. Start a pinned etherpad/etherpad container bound to 127.0.0.1:9001, or complete the source installation and run the service on that address.
  5. Configure persistent storage, database variables, and protected secrets.
  6. Configure Caddy, NGINX, or Traefik for the hostname and verify WebSocket forwarding.
  7. Enable HTTPS at the proxy, then set trustProxy: true in Etherpad’s configuration.
  8. Create a pad, edit from two browsers, refresh, and test a reconnect.
  9. Take the first backup and perform a test restore before treating the instance as production.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

CaddyDockerEtherpadHTTPSLinuxNGINXself-hostingVPSWebSockets

Leave a Reply

Your email address will not be published. Required fields are marked *

Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Recommended PC Tool
Recommended PC Tool
Crashes, No Sound, or Screen Glitches?Free driver scan
Windows Errors? Fix Them Before They SpreadFree repair scan

Two free Windows tools

One Free Minute Could Fix That PC

Before you go - each of these free tools takes about a minute and tackles what quietly slows a Windows PC down.

Special offer. View Outbyte info, uninstall instructions, EULA, and Privacy Policy.