Deployment guide

Etherpad

Overview

Etherpad is an open-source, real-time collaborative document editor. Several people can edit the same document at once and see each other's changes instantly. Each author gets colored text, and there is a built-in chat sidebar and a full revision timeslider.

This image installs Etherpad 2.7.3 as a systemd service bound to loopback, behind an nginx reverse proxy on port 80. The database sits on a dedicated Azure data disk, and every VM generates its own admin password on first boot.

What you get:

Etherpad 2.7.3 (at /opt/etherpad) with an embedded SQLite database
Node.js 22 LTS from the official NodeSource repository
nginx on :80 as a reverse proxy to the loopback Etherpad backend, with WebSocket upgrade headers for real-time collaboration over socket.io
A per-VM admin password generated on first boot and recorded in a root-only file
A dedicated Azure data disk at /var/lib/etherpad for the database (etherpad.db)
etherpad.service and nginx.service as systemd units, enabled and active
24/7 SecureAnyCloud support

Prerequisites

You need an active Azure subscription, an SSH key pair, and a VNet and subnet in the target region. Standard_B2ms (2 vCPU / 8 GiB RAM) is a good starting point.

For NSG inbound rules, allow 22/tcp from your management network and 80/tcp. Etherpad serves plain HTTP on port 80. For production, terminate TLS in front of it with your own domain.

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal. Choose Create a resource, search the Marketplace for Etherpad by SecureAnyCloud, and select Create.

On Basics, pick your subscription, resource group, region and size. Under Administrator account, choose SSH public key and paste your key. Under Inbound port rules, allow SSH (22) and HTTP (80).

Review the dedicated data disk on the Disks tab. Then select Review + create and Create.

Step 2 - Deploy from the Azure CLI

# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:etherpad-ubuntu-24-04:default:latest
az vm create \
  --resource-group <your-rg> \
  --name etherpad \
  --image sac1647283583153:etherpad-ubuntu-24-04:default:latest \
  --size Standard_B2ms \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard
az vm open-port --resource-group <your-rg> --name etherpad --port 80 --priority 1010

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 - Confirm the services are running

systemctl is-active etherpad.service nginx.service

Both services report active. On first boot, the image generates a per-VM admin password and mounts the data disk at /var/lib/etherpad.

findmnt /var/lib/etherpad

The mount is a separate Azure data disk. It is captured into the image and re-provisioned on every VM.

Step 5 - Retrieve your admin password

Your VM generates a unique admin password on first boot and writes it to a root-only file:

sudo cat /root/etherpad-credentials.txt

The file contains etherpad.admin.user (admin) and etherpad.admin.pass, along with the editor and admin URLs. Store the password somewhere safe.

Step 6 - Confirm the editor is serving

Etherpad answers on port 80. nginx proxies to the loopback backend on 9001:

curl -s -o /dev/null -w '%{http_code}\n' http://localhost/

It returns 200, which is the pad index page. You can also confirm the installed version:

node -e "console.log('Etherpad', require('/opt/etherpad/src/package.json').version)"

It prints Etherpad 2.7.3.

Step 7 - Open a pad and collaborate

Browse to http://<vm-public-ip>/. You land on a new pad. Anyone you share the pad URL with can edit the same document in real time. Changes appear instantly, and each author's text is highlighted in their own color.

The toolbar offers formatting, an authorship view, the revision timeslider, and import and export.

Open the Chat panel at the bottom right of any pad to message everyone editing with you, without leaving the document.

To create a named pad, append a name to the URL, for example http://<vm-public-ip>/p/team-standup. Everyone who opens that link joins the same live document.

Step 8 - Open the admin dashboard

Browse to http://<vm-public-ip>/admin/. The dashboard prompts for the admin credentials from Step 5 (username admin).

After you sign in, you can install plugins, edit the live settings.json, manage pads, configure communication, and view troubleshooting information.

Step 9 - Verify admin authentication from the command line

HTTP Basic authentication protects the admin area at /admin-auth/. It rejects an unauthenticated request and a wrong password, and accepts the per-VM admin password. Read the password into a variable, then test all three cases:

PW=$(sudo grep '^etherpad.admin.pass=' /root/etherpad-credentials.txt | cut -d= -f2-)
curl -s -o /dev/null -w '%{http_code}\n' http://localhost/admin-auth/
curl -s -o /dev/null -w '%{http_code}\n' -u "admin:$PW" http://localhost/admin-auth/
curl -s -o /dev/null -w '%{http_code}\n' -u "admin:wrong-password" http://localhost/admin-auth/

The three responses are 401 (unauthenticated), 200 (correct password) and 401 (wrong password).

Step 10 - Confirm data lives on the dedicated disk

Etherpad stores its database on the dedicated Azure data disk. The database survives OS changes, and you can resize the disk independently:

sudo ls -la /var/lib/etherpad/etherpad.db

The SQLite database file (etherpad.db) lives on the data disk mounted at /var/lib/etherpad. The disk is captured into the image and re-provisioned on every VM.

Working with Etherpad

Pads: every URL under /p/<name> is its own live document with a shareable link, colored authorship, chat and a revision timeslider (the clock icon in the toolbar).
API: Etherpad exposes an HTTP API for creating pads, setting text, and managing groups and sessions programmatically. The API key is at /opt/etherpad/APIKEY.txt and is rotated per VM on first boot.
Plugins: install community plugins from the admin Plugin manager. Examples include PDF export, authentication backends and themes.

See the Etherpad documentation for the API reference, plugins and configuration options.

Maintenance

Admin password: the per-VM password is in /root/etherpad-credentials.txt. To change it, edit users.admin.password in /opt/etherpad/settings.json, then run sudo systemctl restart etherpad.
Settings: the live configuration is /opt/etherpad/settings.json. Restart the service after edits.
Data: the SQLite database lives at /var/lib/etherpad/etherpad.db. Snapshot the /var/lib/etherpad data disk to back it up.
TLS: Etherpad serves plain HTTP on port 80. For production, front it with TLS (for example with certbot) and your own domain.
Upgrades: pull a newer Etherpad tag into /opt/etherpad. Re-run bin/installDeps.sh and pnpm run build:etherpad, then run sudo systemctl restart etherpad.
Security patches: unattended-upgrades stays enabled, so the OS keeps receiving security updates automatically.

Support

SecureAnyCloud provides 24/7 expert support for this image. Contact sales@secureanycloud.com.

Deploy on Azure

Launch Etherpad on Ubuntu 24.04 LTS on Azure with 24/7 support from SecureAnyCloud.

View this image

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com

Deploy on Azure

Overview

Etherpad is an open-source online editor for real-time collaborative editing. Several people can edit the same pad at once, each in their own color, and see every keystroke as it happens. It also has a built-in chat, full revision history, and a timeslider that replays how a document was written.

This image installs Etherpad under /opt/etherpad on Node.js 24. It runs as a systemd service under a dedicated unprivileged etherpad system account. The service starts on boot and restarts on failure.

What you get:

An embedded SQLite pad database at /var/lib/etherpad/etherpad.db, on a dedicated, independently resizable EBS data volume, so your pad content survives instance replacement
Etherpad bound to the loopback interface only, never exposed directly
An nginx reverse proxy that publishes the pad editor and the admin settings panel on port 80
WebSocket upgrade headers in the bundled proxy, so live collaboration works out of the box
A pad editor at / that is open to anyone with the pad URL, which is standard for Etherpad
An admin settings panel at /admin, protected by HTTP Basic authentication
An admin password generated on the first boot of every instance, so two instances launched from the same Amazon Machine Image never share a password. It is written to /root/etherpad-credentials.txt with mode 0600, so only root can read it

Prerequisites

Before you deploy this image, make sure you have:

An Amazon Web Services account where you can launch EC2 instances
IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
An EC2 key pair in the target Region for SSH access to the instance
A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and port 80 for the pad editor and the admin panel
The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images, choose AWS Marketplace AMIs and search for Etherpad. Select the SecureAnyCloud listing, choose Select, then choose Continue on the subscription summary.

Pick an instance type of t3.small or larger. Choose your EC2 key pair under Key pair (login).

Under Network settings, select your VPC and subnet. Create or select a security group that opens port 22 from your management network and port 80 for the editor and admin panel. Leave the root volume at the default size or larger.

Select Launch instance. First-boot initialization takes a few seconds after the instance state becomes Running and the status checks pass.

Launch the Instance from the AWS CLI

The following command launches an instance from the SecureAnyCloud Etherpad Marketplace AMI into an existing subnet and security group. Replace the values in angle brackets:

Replace <ami-id> with the AMI ID shown on the Marketplace listing.
Replace <key-name> with your EC2 key pair name.
Replace <subnet-id> with your subnet ID.
Replace <security-group-id> with a security group that opens ports 22 and 80, as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type t3.small \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=etherpad}]'

When the instance reaches the Running state and its status checks pass, note its public IP address or DNS name. You can find it in the EC2 console or with aws ec2 describe-instances.

Connect to Your Instance

Connect over SSH with your key pair. On Ubuntu 24.04, the SSH login user is ubuntu.

ssh -i <key-name>.pem ubuntu@<public-ip>

Retrieve the Admin Password

The admin password is unique to your instance. It was generated on first boot. Read it as root:

sudo cat /root/etherpad-credentials.txt

The file lists the editor URL, the admin panel URL, the admin user (admin) and the generated password. Store the password somewhere safe.

Create and Share a Pad

nginx serves the Etherpad editor on port 80, with full WebSocket support for live collaboration. In a browser, go to:

http://<instance-public-ip>/

The home page lets you create a new pad with a random name or open a named pad. Open a pad and start typing. Everything you write is synchronized in real time. Anyone you share the pad URL with sees your edits as you make them, with each author shown in a distinct color.

To collaborate, copy the pad URL from your browser address bar and send it to others. The pad editor is open to anyone with the URL, which is standard Etherpad behavior.

To require authentication for pads, or to use named authors and groups, install one of the authentication plugins from the admin panel. You can also set requireAuthentication in the settings file.

The toolbar provides bold, italic, lists, headings, color highlighting, undo and redo, and import and export. It also has the timeslider for replaying the pad history. The chat panel in the bottom right corner lets you talk to other editors without leaving the document.

The Admin Settings Panel

The admin settings panel is served at /admin behind HTTP Basic authentication. In a browser, go to:

http://<instance-public-ip>/admin/

The page prompts for credentials. Sign in as admin with the password from the credentials file. The settings page shows the resolved live Etherpad configuration, which you can edit and save from the browser.

Open the plugin manager from the admin panel. It lists the installed plugins and lets you search the public catalog of community plugins. These cover authentication, export formats, formatting, integrations and more. Installing a plugin restarts Etherpad automatically.

Confirm Etherpad Is Running

Over SSH, confirm that Etherpad and the nginx proxy are active and that the ports are listening:

sudo systemctl is-active etherpad nginx
sudo ss -tlnp | grep -E ':(80|9001) '

Both services report active. Etherpad listens on 127.0.0.1:9001 (loopback only), and nginx listens on port 80.

How the WebSocket Proxy Works

Etherpad's real-time collaboration runs over a socket.io WebSocket. The bundled nginx site upgrades the connection, so live editing works without extra configuration. To confirm that the proxy upgrades WebSocket connections, inspect the site configuration:

sudo grep -E 'Upgrade|Connection|proxy_pass' /etc/nginx/sites-available/etherpad

The output shows the proxy_set_header Upgrade and proxy_set_header Connection directives and the proxy_pass to http://127.0.0.1:9001.

If you put your own proxy or load balancer in front of this instance, it must forward the Upgrade and Connection headers in the same way. Otherwise the editor loads but never connects.

The Data Volume

The pad database lives on a dedicated EBS volume mounted at /var/lib/etherpad. This keeps your pad content off the operating system disk and lets you resize or snapshot the volume independently. Confirm the mount with:

df -h /var/lib/etherpad

To grow the database volume, expand the EBS volume in the AWS console. Then grow the filesystem on the instance with sudo resize2fs on the underlying device.

The SQLite database suits small to medium teams. For large deployments with many concurrent editors, switch Etherpad to an external database such as PostgreSQL or MySQL. Edit dbType and dbSettings in /opt/etherpad/settings.json, then restart the service.

Enable HTTPS

nginx serves the editor and admin panel over plain HTTP on port 80. For production, place them behind TLS.

Obtain a certificate for your domain. For example, use a managed certificate on an Application Load Balancer in front of the instance, or install Certbot on the instance.

Then configure nginx to listen on 443 with your certificate and proxy to 127.0.0.1:9001, exactly as the bundled site does for port 80. Keep the WebSocket upgrade headers in place.

Restrict the security group so that ports 80 and 443 are reachable only from the networks that use the editor.

Backup and Maintenance

Back up your pads by snapshotting the /var/lib/etherpad EBS volume. The snapshot captures the entire SQLite pad database.

Apply operating system security updates with sudo apt-get update && sudo apt-get upgrade. Reboot when a new kernel is installed. Etherpad and nginx start automatically on boot.

To restart Etherpad after a configuration change, run sudo systemctl restart etherpad.

Support

SecureAnyCloud publishes and supports this image. Support covers deployment, plugin installation, authentication and access control, export formats, database tuning, and TLS and reverse proxy configuration. Contact SecureAnyCloud through the support channel listed on the AWS Marketplace listing.

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.

Deploy on AWS

Launch Etherpad on AWS with 24/7 support from SecureAnyCloud.

View on Marketplace

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com

Deploy on AWS