Skip to content

Latest commit

 

History

History
297 lines (212 loc) · 8.2 KB

README.md

File metadata and controls

297 lines (212 loc) · 8.2 KB

Etherpad-Go-EXPERIMENTAL

A fast, modern, real-time collaborative editor written in Go

CI Go Version License Release Docker Image

Etherpad-Go is a performance-focused, 1:1(currently partial) rewrite of Etherpad in Go. The original implementation was written in Node.js (CommonJS). Rewriting Etherpad in Go allows us to leverage Go’s concurrency model, static typing, fast startup times, and lower memory usage however there are trade offs and this is an experimental branch so YMMV!

Etherpad-Go Logo

Etherpad in action

Etherpad is a real-time collaborative editor scalable to thousands of simultaneous users and supports full data export.


Quick Start (Binary)

The easiest way to run Etherpad-Go:

  1. Download the binary for your platform from the
    Releases page
  2. Run it:
./etherpad-go

Etherpad-Go starts in under a second and uses an in-memory database by default, which is sufficient for many use cases.

Open your browser at:
http://localhost:9001


Configuration

All configuration options are self-documented in the binary.

Show global options:

./etherpad-go --help

Show all configuration values:

./etherpad-go config show

Get a specific configuration value:

./etherpad-go config get <key>

In the Docker image the same commands work through docker exec (see Docker).

For customization, copy:

settings.json.template → settings.json

and adjust it to your needs.

Behind a reverse proxy under a path

Etherpad can be served under a path such as https://example.org/pads/. The proxy strips the prefix and names it in the x-proxy-path header, for example with nginx:

location /pads/ {
    proxy_pass http://127.0.0.1:9001/;
    proxy_set_header x-proxy-path /pads;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

With "trustProxy": true the standard X-Forwarded-Prefix (Traefik, HAProxy) and X-Ingress-Path (Home Assistant) work too; without it they are ignored, since any client could send them when Etherpad is reachable directly. Pages, the admin UI, the websockets and /manifest.json then stay under the prefix. Pages that carry the prefix answer with Vary on these headers and are not stored by shared caches.


Docker

You can run Etherpad-Go using Docker.

Docker Compose (recommended)

Start Etherpad-Go with PostgreSQL:

docker compose up -d

Etherpad will be available at:
http://localhost:9001

The compose file can be found here:
docker-compose.yml

Build your own image

docker build -t etherpad-go .

Prebuilt images

Prebuilt images are available via GitHub Container Registry:

ghcr.io/ether/etherpad-go:<version>

To open a shell in a running container (busybox: ls, cat, less, grep, vi, …, no network tools):

docker exec -it etherpad_go sh

The configuration CLI is the image's etherpad-go, on the PATH:

docker exec etherpad_go etherpad-go config show
docker exec etherpad_go etherpad-go config get port

Files and the user in the image

The server runs as the unprivileged user 65532. It writes to two directories, which belong to that user in the image:

Directory What Mount a volume here for
/var the SQLite database (var/etherpad.db, the default) and the update state SQLite
/data settings.json (ETHERPAD_SETTINGS_FILE=/data/settings.json), also as saved in the admin UI settings

The ownership in the image only covers the directories themselves and a named Docker volume created from them. A host directory you bind-mount at /var or /data keeps its own owner and must be writable for 65532, or the server cannot open SQLite or save settings from the admin UI:

sudo chown -R 65532:65532 ./etherpad-data

A settings.json mounted at /settings.json is still read, as long as /data/settings.json does not exist. Settings saved in the admin UI go to /data/settings.json, which is then the one read. /APIKEY.txt and relative favicon paths are still looked up in /. If a settings file exists but cannot be read (no permission), the server does not start rather than fall back to the defaults.

Upgrading from an image that ran as root: a volume on /var belongs to root, and the server stops with attempt to write a readonly database. Hand it over once:

docker run --rm -v <volume>:/var alpine chown -R 65532:65532 /var

With Postgres or MySQL and no volume, nothing changes.

Several instances / Kubernetes

With PostgreSQL or MySQL, several Etherpad-Go instances can share one database behind a stateless load balancer or Ingress — no sticky sessions needed. The instances find each other through the database and only need to reach each other on port 7946 (TCP and UDP). See doc/cluster.md for how it works, the settings and a Kubernetes example.


Building from Source

Requirements

Installation

  1. Clone the repository:

    git clone https://github.com/ether/etherpad-go.git
    cd etherpad-go
  2. Build etherpad-go:

    go run main.go prepare
  3. Run the server. The server path is printed after a successful build:

    ./<your-built-binary>

Etherpad should start in less than a second.


Migration from Etherpad-Lite

You can migrate existing pads from Etherpad-Lite using the migration command:

migration 192.28.91.4:5432 \
  --type postgres \
  --username myOldEtherpadDBUser \
  --database myoldEtherpadDB

This connects to the old Etherpad-Lite database and migrates all pads to the Etherpad-Go database configured in settings.json or via environment variables.


Plugins

Etherpad-Go ships with 15 built-in plugins ported from the original Etherpad ecosystem. All plugins are disabled by default and can be enabled individually.

Available Plugins

Plugin Description
ep_align Text alignment (left, center, right, justify)
ep_author_hover Show author name on text hover
ep_chat_log_join_leave Log user join/leave events in the chat
ep_clear_formatting Remove all formatting from selected text
ep_cursortrace Show other users' cursor positions in real time
ep_font_color Change text color (6 colors)
ep_font_family Change font family (10 fonts)
ep_font_size Change font size (15 sizes from 8px to 60px)
ep_heading Heading levels (h1-h4)
ep_markdown Markdown editing support
ep_print Print the pad
ep_rss RSS feed for pad content
ep_spellcheck Browser spell checking
ep_table_of_contents Sidebar table of contents from headings

Enabling Plugins

Via settings.json:

{
  "plugins": {
    "ep_align": { "enabled": true },
    "ep_cursortrace": { "enabled": true },
    "ep_font_color": { "enabled": true }
  }
}

Or via environment variables:

ETHERPAD_PLUGINS_EP_ALIGN_ENABLED=true
ETHERPAD_PLUGINS_EP_CURSORTRACE_ENABLED=true

Status

Etherpad-Go is under active development. Feedback, issues, and contributions are welcome.