Etherpad on AWS User Guide

Overview

This image runs Etherpad, the open source online editor that provides real-time collaborative editing of documents. Multiple people can edit the same pad simultaneously, each shown in their own colour, seeing every keystroke as it happens, with a built in chat, full revision history and a timeslider that replays how a document was written.

Etherpad is installed under /opt/etherpad on Node.js 24 and runs as a dedicated unprivileged etherpad system account under a systemd service that starts it on boot and restarts it on failure. The pad database is an embedded SQLite database stored at /var/lib/etherpad/etherpad.db, which lives on a dedicated, independently resizable EBS data volume so all of your pad content survives instance replacement.

Etherpad binds to the loopback interface only and is never exposed directly. An nginx reverse proxy publishes the pad editor and the admin settings panel on port 80. Because Etherpad's real-time collaboration runs over a WebSocket, the bundled proxy is configured to upgrade the connection, so live collaboration works out of the box. The pad editor at / is open to anyone with the pad URL, which is standard for Etherpad. The admin settings panel at /admin is gated by HTTP Basic authentication. The admin password is generated on the first boot of every deployed 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 that only the root user can read it.

Prerequisites

Before you deploy this image you need:

• 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

Step 1: 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 cloudimg listing and choose Select, then 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, and either 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 initialisation takes a few seconds after the instance state becomes Running and the status checks pass.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg Etherpad Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <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 from the EC2 console or with aws ec2 describe-instances.

Step 3: Connect to Your Instance

Connect over SSH using your key pair and the login user for your operating system variant.

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

Step 4: Retrieve the Admin Password

The admin password is unique to your instance and 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. Keep this password somewhere safe.

Step 5: Create and Share a Pad

The Etherpad editor is served on port 80 by nginx 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 synchronised in real time, so anyone you share the pad URL with sees your edits as you make them, each author shown in a distinct colour.

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 behaviour. To require authentication for pads, or to use named authors and groups, install one of the authentication plugins from the admin panel or set requireAuthentication in the settings file.

The toolbar provides bold, italic, lists, headings, colour highlighting, undo and redo, import and export, the timeslider for replaying the pad history, and the chat panel in the bottom right corner for talking to other editors without leaving the document.

Step 6: 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/

You are prompted 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.

The plugin manager, reached from the admin panel, lists the plugins currently installed and lets you search the public catalogue of hundreds of community plugins for authentication, export formats, formatting, integrations and more. Installing a plugin restarts Etherpad automatically.

Step 7: Confirm Etherpad Is Running

Over SSH, confirm 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) '

You should see both services reported as active, Etherpad listening on 127.0.0.1:9001 (loopback only), and nginx listening on port 80.

Step 8: 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 any extra configuration. You can confirm the proxy is upgrading WebSocket connections by inspecting the site configuration:

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

You will see 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, or the editor will load but never connect.

Step 9: 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 it 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 is suitable for small to medium teams. For large deployments with many concurrent editors, switch Etherpad to an external database such as PostgreSQL or MySQL by editing the dbType and dbSettings in /opt/etherpad/settings.json and restarting the service.

Step 10: Enable HTTPS

The editor and admin panel are served over plain HTTP on port 80 by nginx. For production use, place them behind TLS. Obtain a certificate for your domain (for example with a managed certificate on an Application Load Balancer in front of the instance, or with Certbot installed 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, keeping the WebSocket upgrade headers in place. Restrict the security group so ports 80 and 443 are reachable only from the networks that use the editor.

Step 11: Backup and Maintenance

Back up your pads by snapshotting the /var/lib/etherpad EBS volume, which captures the entire SQLite pad database. Apply operating system security updates with sudo apt-get update && sudo apt-get upgrade and 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

This image is published and supported by cloudimg. Support covers deployment, plugin installation, authentication and access control, export formats, database tuning, TLS and reverse proxy configuration. Contact cloudimg 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.