Deploying Etherpad

Introduction

Etherpad is a highly customizable, open-source, web-based collaborative real-time editor that allows multiple users to work on the same document simultaneously. With features like real-time synchronization, extensive plugin support, and easy customization, Etherpad is ideal for team collaboration, note-taking, documentation, and brainstorming sessions. Whether you’re building a collaborative writing platform, an internal team tool, or a public notepad service, Etherpad provides a robust foundation for real-time text editing.

Deploying Etherpad on Klutch.sh provides you with a scalable, reliable infrastructure optimized for collaborative applications. With support for persistent storage, automatic Dockerfile detection, and easy configuration, you can have your Etherpad instance up and running in minutes.

This comprehensive guide walks you through deploying Etherpad on Klutch.sh using a Dockerfile. You’ll learn how to install and configure Etherpad, create a production-ready Dockerfile, set up persistent storage for your data, and deploy your application with best practices for security and performance.

---

Prerequisites

Before you begin, make sure you have:

• A Klutch.sh account (sign up if you haven’t already)
• A GitHub account and basic Git knowledge
• Basic familiarity with Docker and containerization concepts
• Node.js and npm installed locally (for testing)

---

Getting Started: Installing Etherpad Locally

Before deploying to Klutch.sh, let’s set up Etherpad locally to understand how it works and test your configuration.

Step 1: Clone the Etherpad Repository

git clone https://github.com/ether/etherpad-lite.git
cd etherpad-lite

Step 2: Install Dependencies

Etherpad requires Node.js (version 16.x or higher) and npm:

npm install

This will install all necessary dependencies for running Etherpad.

Step 3: Configure Etherpad (Optional)

Etherpad comes with a default settings.json file. You can customize it for your needs:

cp settings.json.template settings.json

Edit settings.json to configure:

• Database settings (default is DirtyDB, but MySQL/PostgreSQL are recommended for production)
• Port configuration (default is 9001)
• Admin credentials
• Session key and trust proxy settings

Example basic configuration:

{
  "title": "Etherpad on Klutch.sh",
  "ip": "0.0.0.0",
  "port": 9001,
  "dbType": "dirty",
  "dbSettings": {
    "filename": "var/dirty.db"
  },
  "defaultPadText": "Welcome to Etherpad on Klutch.sh!\\n\\nStart collaborating now!",
  "trustProxy": true
}

Step 4: Run Etherpad Locally

Start the Etherpad server:

npm start

Or use the start script:

./bin/run.sh

Visit http://localhost:9001 in your browser to see Etherpad running locally. You should see the default Etherpad interface where you can create and edit pads.

---

Creating a Dockerfile for Etherpad

To deploy Etherpad on Klutch.sh, you’ll need a Dockerfile. Klutch.sh automatically detects a Dockerfile in your repository’s root directory and uses it to build your container.

Basic Dockerfile

Create a file named Dockerfile in your project root:

# Use the official Etherpad image as base
FROM etherpad/etherpad:latest

# Set working directory
WORKDIR /opt/etherpad-lite

# Copy custom settings if you have any
# COPY settings.json /opt/etherpad-lite/settings.json

# Expose Etherpad port
EXPOSE 9001

# Etherpad starts automatically with the official image

This Dockerfile uses the official Etherpad image, which includes all necessary dependencies and configurations.

Production Dockerfile with Custom Configuration

For more control and customization, you can build from a Node.js base image:

# Use Node.js LTS as base
FROM node:18-alpine

# Install required system dependencies
RUN apk add --no-cache \
    git \
    curl \
    python3 \
    make \
    g++

# Set working directory
WORKDIR /opt/etherpad-lite

# Clone Etherpad repository (or copy your forked version)
RUN git clone --branch master https://github.com/ether/etherpad-lite.git . && \
    git checkout $(git describe --tags --abbrev=0)

# Install Etherpad dependencies
RUN npm install --production && \
    npm cache clean --force

# Create var directory for database
RUN mkdir -p var

# Copy custom settings
COPY settings.json /opt/etherpad-lite/settings.json

# Expose port
EXPOSE 9001

# Set environment variable
ENV NODE_ENV=production

# Start Etherpad
CMD ["node", "node_modules/ep_etherpad-lite/node/server.js"]

Dockerfile with Database Support

For production deployments with MySQL or PostgreSQL:

FROM node:18-alpine

# Install dependencies including database clients
RUN apk add --no-cache \
    git \
    curl \
    python3 \
    make \
    g++ \
    mysql-client \
    postgresql-client

WORKDIR /opt/etherpad-lite

# Clone and install Etherpad
RUN git clone --branch master https://github.com/ether/etherpad-lite.git . && \
    npm install --production && \
    npm cache clean --force

# Create necessary directories
RUN mkdir -p var

# Copy custom configuration
COPY settings.json /opt/etherpad-lite/settings.json

EXPOSE 9001

ENV NODE_ENV=production

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
    CMD curl -f http://localhost:9001/ || exit 1

CMD ["node", "node_modules/ep_etherpad-lite/node/server.js"]

---

Deploying Etherpad on Klutch.sh

Now that you have your Dockerfile ready, let’s deploy Etherpad to Klutch.sh.

Step 1: Push Your Code to GitHub

1. Create a new GitHub repository for your Etherpad deployment.

2. Initialize Git in your project directory (if not already done):

   git init

3. Add your files to the repository:

   git add Dockerfile settings.json
   git commit -m "Add Etherpad Dockerfile and configuration"

4. Link to your GitHub repository and push:

   git remote add origin https://github.com/yourusername/etherpad-deployment.git
   git branch -M main
   git push -u origin main

Step 2: Create a Project on Klutch.sh

1. Log in to your Klutch.sh dashboard.

2. Navigate to Create a new project.

3. Give your project a descriptive name (e.g., “Etherpad Collaboration Platform”).

4. Click “Create Project”.

Step 3: Create and Configure Your App

1. Inside your project, navigate to Create a new app.

2. Connect Your GitHub Repository:

   • Select your Etherpad GitHub repository from the list
   • Choose the branch you want to deploy (e.g., main)

3. Configure Traffic Type:

   • Select HTTP as the traffic type (Etherpad is a web application)

4. Set the Internal Port:

   • Set the internal port to 9001 (Etherpad’s default port)
   • This is the port your container listens on internally

5. Select Region and Compute Resources:

   • Choose the region closest to your users
   • Select appropriate compute resources based on your expected traffic
   • For small to medium deployments, start with 1-2 instances

6. Configure Environment Variables: Add any necessary environment variables for your Etherpad configuration:

   • ADMIN_PASSWORD - Password for admin access
   • DB_TYPE - Database type (e.g., mysql, postgres, or dirty)
   • DB_HOST - Database hostname (if using external database)
   • DB_PORT - Database port
   • DB_NAME - Database name
   • DB_USER - Database username
   • DB_PASS - Database password
   • SESSION_KEY - Session encryption key (generate a random string)
   • TRUST_PROXY - Set to true if behind a proxy

Step 4: Configure Persistent Storage

Etherpad stores data in the var directory. To ensure your pads persist across deployments, you need to attach a persistent volume.

1. In your app settings on Klutch.sh, navigate to the Volumes section.

2. Click Add Volume to create a new persistent volume.

3. Configure the volume:

   • Mount Path: /opt/etherpad-lite/var
   • Size: Start with 5GB (adjust based on your needs)

4. Save the volume configuration.

This ensures that your Etherpad database, pad data, and any uploaded files are persisted even when your container restarts or is redeployed.

Step 5: Deploy Your Application

1. Review all your configuration settings.

2. Click “Create” to start the deployment.

3. Klutch.sh will:

   • Detect your Dockerfile automatically
   • Build the Docker image from your repository
   • Deploy the container with your specified configuration
   • Set up networking and routing

4. Monitor the build process in the deployment logs.

Once the deployment is complete, your Etherpad instance will be available at a URL like example-app.klutch.sh.

---

Post-Deployment Configuration

Accessing Your Etherpad Instance

Visit your deployed application URL (e.g., example-app.klutch.sh) to access your Etherpad instance. You should see the Etherpad homepage where you can create new pads.

Setting Up Admin Access

To access the admin interface:

1. Navigate to https://example-app.klutch.sh/admin
2. Log in with your admin credentials (configured via environment variables)
3. From the admin panel, you can:
   • Manage plugins
   • View system settings
   • Monitor active pads
   • Configure additional settings

Installing Plugins

Etherpad supports numerous plugins for extended functionality. To install plugins:

1. Access the admin panel at /admin
2. Navigate to the “Plugin Manager” section
3. Search for and install plugins such as:
   • ep_comments_page - Add commenting functionality
   • ep_markdown - Markdown support
   • ep_headings2 - Heading support
   • ep_font_color - Text color options

Alternatively, you can add plugins to your Dockerfile:

# Install plugins during build
RUN npm install --no-save \
    ep_markdown \
    ep_comments_page \
    ep_headings2

---

Database Configuration

While Etherpad’s default DirtyDB works for small deployments, production environments should use a proper database.

Using MySQL

Update your settings.json:

{
  "dbType": "mysql",
  "dbSettings": {
    "host": "your-mysql-host",
    "port": 3306,
    "database": "etherpad",
    "user": "etherpad_user",
    "password": "secure_password",
    "charset": "utf8mb4"
  }
}

You can also configure database settings using environment variables in your Klutch.sh app settings instead of modifying settings.json. Set these in the dashboard:

• DB_TYPE (e.g., mysql)
• DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASS for connection details

Using PostgreSQL

Update your settings.json:

{
  "dbType": "postgres",
  "dbSettings": {
    "host": "your-postgres-host",
    "port": 5432,
    "database": "etherpad",
    "user": "etherpad_user",
    "password": "secure_password"
  }
}

---

Environment Variables Reference

Configure these environment variables in the Klutch.sh dashboard:

Variable	Description	Example
TITLE	Instance title	"My Etherpad"
PORT	Port number (internal)	9001
ADMIN_PASSWORD	Admin interface password	secure_admin_pass
DB_TYPE	Database type	mysql, postgres, dirty
DB_HOST	Database host	db.example.com
DB_PORT	Database port	3306
DB_NAME	Database name	etherpad
DB_USER	Database user	etherpad_user
DB_PASS	Database password	secure_password
SESSION_KEY	Session encryption key	random_key_here
TRUST_PROXY	Trust proxy headers	true

---

Scaling and Performance

Horizontal Scaling

Etherpad can be scaled horizontally for high-traffic scenarios:

1. Increase the number of instances in your Klutch.sh app settings
2. Ensure you’re using a centralized database (MySQL/PostgreSQL)
3. Configure session storage to use the database or Redis

Performance Optimization

• Use a production database: MySQL or PostgreSQL instead of DirtyDB
• Enable caching: Configure Redis for session and cache storage
• Optimize plugins: Only install necessary plugins to reduce overhead
• Monitor resources: Use Klutch.sh monitoring to track CPU and memory usage

---

Security Best Practices

1. Use Strong Admin Passwords:

   • Generate secure passwords for admin access
   • Store credentials as secrets in environment variables

2. Enable Authentication:

   • Consider installing authentication plugins
   • Restrict access to sensitive pads

3. Regular Updates:

   • Keep Etherpad updated to the latest version
   • Update your Docker base image regularly
   • Monitor security advisories

4. Secure Database Connections:

   • Use encrypted connections to your database
   • Store database credentials securely as environment variables

5. Configure Trust Proxy:

   • Set TRUST_PROXY to true when behind a reverse proxy
   • This ensures correct IP logging and security checks

---

Troubleshooting

Application Won’t Start

• Check deployment logs in the Klutch.sh dashboard
• Verify that the internal port is set to 9001
• Ensure all required environment variables are set
• Check that the Dockerfile builds successfully locally

Database Connection Issues

• Verify database credentials in environment variables
• Ensure network connectivity between app and database
• Check database host and port settings
• Test connection with a database client

Pads Not Persisting

• Verify that persistent volume is attached to /opt/etherpad-lite/var
• Check volume mount path in Klutch.sh settings
• Ensure proper file permissions in the container

Performance Issues

• Monitor resource usage in Klutch.sh dashboard
• Consider scaling to larger compute resources
• Optimize database queries and indexes
• Review and remove unnecessary plugins

---

Resources

• Etherpad GitHub Repository
• Official Etherpad Documentation
• Klutch.sh Quick Start Guide
• Klutch.sh Persistent Volumes Guide
• Klutch.sh Builds Documentation
• Custom Domains on Klutch.sh

---

Deploying Etherpad on Klutch.sh provides a robust, scalable platform for collaborative editing. With automatic Dockerfile detection, persistent storage support, and easy configuration, you can focus on building your collaborative application while Klutch.sh handles the infrastructure. Whether you’re running a small team collaboration tool or a large-scale public pad service, Klutch.sh gives you the flexibility and reliability you need.