98dbba4f1f
* test(ci): heartbeat + running-test pointer in backend test diagnostics Backend tests silently die with code 255 mid-suite ~22% of the time on develop (most often Windows-with-plugins, Node 24). Each kill lands 300±50 ms after the previous test's clean ✔ teardown line and produces no failing-test marker, no error, no Mocha summary, and — despite the unconditional handlers in `diagnostics.ts` — none of the JS-level death events fire either. Recent example: run 26311025244 (`Windows with Plugins (24)`); both attempts crashed at completely different "last test" locations, so the dying test itself isn't to blame. The existing diagnostics only set lastSeenTest in afterEach, so if the kill lands during the NEXT test's setup or body — which is exactly the ~300ms gap we observe — the pointer reads as the previous (passing) test. That hides whether we're between tests or inside one, and which one. Two changes: 1. Track currentTest in beforeEach as well as lastFinishedTest in afterEach. Every diag line now carries both, so the death point is bracketable regardless of which lifecycle phase the kill interrupts. 2. Add a 1Hz heartbeat that writeSyncs the running-test name plus `process.memoryUsage()` (rss, heap) and the active-handle and active-request counts. The interval is unref'd so it never holds the event loop open by itself. Cost is roughly one extra log line per second of mocha runtime (~60-120 lines per CI run). When the next failure fires, the last heartbeat narrows the kill window to ≤1s, the running pointer names the test on the rails at that moment, and the handle/memory trace gives a sparkline that exposes sudden spikes — a leaked socket, an unref'd timer, a runaway map — that would otherwise be invisible at the runner-log level. No behavior change on successful runs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix: heartbeat _getActiveHandles optional chain bug (Qodo #2) Qodo correctly flagged `_getActiveHandles?.().length` as a latent TypeError: `?.()` guards the call but the call's `undefined` return on a missing method still hits `.length`, which throws. Since the heartbeat fires on a setInterval inside the mocha bootstrap, a Node build without the underscore-prefixed internals would take down the whole backend test run. Capture the array first, then read `.length` only when it actually exists. -1 stays as the "API missing" sentinel. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test(ci): per-test start diag + drop stray console.log noise Follow-up to the heartbeat PR after run 26397693748 confirmed the diagnostic works (the kill landed at importexportGetPost.ts 'Import authorization checks > authn anonymous !exist -> fail', ~300 ms after the previous test's ✔). Two cleanups so the next failure pinpoints faster and reads cleaner: 1. diagnostics.ts: emit a `test start: <name>` diag line in the mocha beforeEach hook, after setting the currentTest pointer. The 1Hz heartbeat misses tests that take less than a second, and the silent kills land ~300 ms after a test boundary — precisely the gap where heartbeat resolution fails. A start line per test gives sub-millisecond resolution on which test was on the rails when the process died. 2. specs/api/importexportGetPost.ts: drop a stray `console.log(importedPads)` debug leftover (and the duplicate `await importEtherpad(records)` only present to feed it) in the `malformed .etherpad files are rejected` block. The leftover dumped a ~600-line reflection of a supertest Response object to the CI log on every successful run, drowning the surrounding test output and making the silent-kill window much harder to read. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test(ci): write node-report on every heartbeat tick Run 26398054688 narrowed the kill to a specific test (pad.ts > Gets text on a pad Id and doesn't have an excess newline) but the test body is a trivial supertest GET — the kill bypasses all JS handlers, so we can't capture stack state at death. Two failures across two runs share the shape: an agent.{get,post} + common.generateJWTToken() call dies ~300-600 ms after test start, with no JS-visible cause. The next step is V8 + native stack. Hook into the existing 1Hz heartbeat to call process.report.writeReport(path) whenever a report directory is set. The Windows backend-tests workflow already wires up `--report-directory=${{ github.workspace }}/node-report` via NODE_OPTIONS and uploads that directory as an artifact on failure, so the rolling snapshots ride for free on the existing upload step. Each report (~50 KB) contains: - V8 + native call stacks for all threads - libuv active handles (open TCP, timers, file handles) - JS heap statistics - resourceUsage + system info - shared-object list On the next reproduction the latest report before ELIFECYCLE will sit ~0-1 s before the kill — enough to see whether the V8 stack is inside jose's WebCrypto sign path, inside supertest's TCP roundtrip, or somewhere unexpected entirely. NODE_REPORT_DIR is also honored as an explicit override for local repro / non-workflow runs. Cost: ~6 files (~300 KB) per Windows backend-test failure, plus ~50 ms event-loop pause per heartbeat. No-op when neither env var is set. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix: writeReport with bare filename, not mixed-slash absolute path Run 26398830249 exposed the path-separator bug in the previous commit: every heartbeat tick on the Windows runner logged Failed to open Node.js report file: D:\a\etherpad\etherpad/node-report/hb-NNNN-...json directory: D:\a\etherpad\etherpad/node-report (errno: 22) — EINVAL. The workflow sets --report-directory with forward-slash separators on Windows, then this code concatenated another `/` plus the filename, producing a path Node's report writer rejects. writeReport(fileName) takes a BARE filename and resolves it against the configured report directory using the platform-correct separator internally. Switch to that. For local repro overrides via NODE_REPORT_DIR, push the path into process.report.directory (the documented config knob) instead of joining it into the call site. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test(ci): write node-report on test boundaries, throttled to 4Hz Run 26398985832 proved the heartbeat-only report cadence isn't tight enough: the last report before the kill was hb-0013 at +16201ms, ~1.5 s before ELIFECYCLE at +17701ms — during which ~30 tests fired, including the dying one (`authn anonymous !exist -> fail`). The captured V8 stack is just our heartbeat code, not the dying test. Move the writeReport call to a shared tryWriteReport() helper and invoke it from BOTH the heartbeat AND mocha's beforeEach hook, throttled to one report per 250 ms. That gives ≤250 ms resolution on the kill window — close enough that the latest report captures state from inside the dying test rather than from the test ~30 slots earlier. The heartbeat always writes (so we don't lose the no-test-running ticks during setup); beforeEach only writes when the throttle window has elapsed. Cost ceiling: ~4 reports/sec × ~12 s test phase ≈ 48 reports (~2.5 MB) per failing run. Each writeReport adds ~50 ms of event-loop pause — at 4Hz that's 20% of wall time spent in diagnostics, which is acceptable for a temporary debug-only bootstrap. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test(ci): drop beforeEach report throttle from 250ms to 100ms Run 26399285213's rerun captured a sixth death point on the new 4Hz cadence (`socketio.ts > Duplicate-author handling > cookie identity: same-author second socket kicks the first`, kill at +45953ms, 271ms after test start). The throttle suppressed the dying test's own beforeEach: previous boundary write landed 128 ms earlier and the next 31 ms after that, both inside the 250 ms window. Last captured report (be-0100) is from the previous test. 100 ms is still well above the inter-test cadence in fast burst suites (tests fire 2-5 ms apart, so 20-50 of them get throttled to a single write, ceiling ~10 writes/sec). But it's tight enough that any death-window neighbour ≥100 ms after the previous report — the shape we keep observing — gets its own boundary snapshot. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> |
||
|---|---|---|
| .github | ||
| admin | ||
| bin | ||
| doc | ||
| docs/superpowers | ||
| local_plugins | ||
| packaging | ||
| snap | ||
| src | ||
| ui | ||
| var | ||
| .dockerignore | ||
| .editorconfig | ||
| .env.default | ||
| .env.dev.default | ||
| .gitattributes | ||
| .gitignore | ||
| .npmrc | ||
| .pr_agent.toml | ||
| AGENTS.MD | ||
| best_practices.md | ||
| CHANGELOG.md | ||
| CONTRIBUTING.md | ||
| docker-compose.dev.yml | ||
| docker-compose.yml | ||
| Dockerfile | ||
| LICENSE | ||
| package.json | ||
| pnpm-lock.yaml | ||
| pnpm-workspace.yaml | ||
| PRIVACY.md | ||
| README.md | ||
| SECURITY.md | ||
| settings.json.docker | ||
| settings.json.template | ||
| tests | ||
Etherpad — the editor for documents that matter
Real-time collaborative editing where authorship is the default, your server is the only server, and you decide what AI (if any) ever touches your text.
About
Etherpad is a real-time collaborative editor for documents that matter.
Every keystroke is attributed to its author. Every revision is preserved. The timeslider lets you scrub through a document's entire history, character by character. Author colours make collaboration visible at a glance — not buried in a menu.
Etherpad runs on your server, under your governance. No telemetry. No upsells. AI is a plugin you install, pointed at the model you choose, running on infrastructure you control — not a feature decided for you in a boardroom you weren't in. See PRIVACY.md for the two opt-out network calls Etherpad's own code makes and how to disable each.
The code is Apache 2.0. The data format is open. It scales to thousands of simultaneous editors per pad. Translated into 105 languages. Extended through hundreds of plugins. Used by Wikimedia, governments, public-sector institutions, and self-hosters worldwide since 2009.
Full data export is built in. The history is yours.
Try it out
Try out a public Etherpad instance
Project Status
Etherpad has been doing the same thing — well — since 2009. No pivots, no acquisitions, no enshittification. Maintained by a small volunteer team.
We are actively looking for maintainers. If you have experience with Node.js, real-time systems, or institutional collaboration tooling and you want to work on infrastructure that thousands of organisations quietly depend on, please open an issue or contact John McLear.
Code Quality
Testing
Engagement
Who uses Etherpad
For more than a decade, Etherpad has quietly underpinned the documents that matter to:
- Wikimedia Foundation — collaborative drafting across editor communities.
- Public-sector institutions across the EU — including organisations that legally cannot use US-cloud SaaS for sovereignty and GDPR reasons.
- Universities and schools worldwide — including jurisdictions where Google Workspace is no longer permitted in education.
- Civic-tech and democratic-deliberation projects — citizen assemblies, participatory budgeting, public consultations.
- Newsrooms and investigative journalism teams — where authorship and editing history matter for legal and editorial integrity.
- Tens of thousands of self-hosted instances worldwide, run by IT teams who chose Etherpad because it is theirs.
Installation
Quick install (one-liner)
The fastest way to get Etherpad running. Requires git and Node.js >= 24.
macOS / Linux / WSL:
curl -fsSL https://raw.githubusercontent.com/ether/etherpad/master/bin/installer.sh | sh
Windows (PowerShell):
irm https://raw.githubusercontent.com/ether/etherpad/master/bin/installer.ps1 | iex
Both installers clone Etherpad into ./etherpad-lite, install dependencies, and
build the frontend. When the installer finishes, run:
cd etherpad-lite && pnpm run prod
Then open http://localhost:9001.
To install and start in one go:
# macOS / Linux / WSL
ETHERPAD_RUN=1 sh -c "$(curl -fsSL https://raw.githubusercontent.com/ether/etherpad/master/bin/installer.sh)"
# Windows
$env:ETHERPAD_RUN=1; irm https://raw.githubusercontent.com/ether/etherpad/master/bin/installer.ps1 | iex
Docker-Compose
The official image is published to both Docker Hub (etherpad/etherpad) and GitHub Container Registry (ghcr.io/ether/etherpad) with identical tags. Use whichever suits your environment; GHCR avoids Docker Hub's anonymous pull rate limits.
services:
app:
user: "0:0"
image: etherpad/etherpad:latest # or: ghcr.io/ether/etherpad:latest
tty: true
stdin_open: true
volumes:
- plugins:/opt/etherpad-lite/src/plugin_packages
- etherpad-var:/opt/etherpad-lite/var
depends_on:
- postgres
environment:
NODE_ENV: production
ADMIN_PASSWORD: ${DOCKER_COMPOSE_APP_ADMIN_PASSWORD:-admin}
DB_CHARSET: ${DOCKER_COMPOSE_APP_DB_CHARSET:-utf8mb4}
DB_HOST: postgres
DB_NAME: ${DOCKER_COMPOSE_POSTGRES_DATABASE:-etherpad}
DB_PASS: ${DOCKER_COMPOSE_POSTGRES_PASSWORD:-admin}
DB_PORT: ${DOCKER_COMPOSE_POSTGRES_PORT:-5432}
DB_TYPE: "postgres"
DB_USER: ${DOCKER_COMPOSE_POSTGRES_USER:-admin}
# For now, the env var DEFAULT_PAD_TEXT cannot be unset or empty; it seems to be mandatory in the latest version of etherpad
DEFAULT_PAD_TEXT: ${DOCKER_COMPOSE_APP_DEFAULT_PAD_TEXT:- }
DISABLE_IP_LOGGING: ${DOCKER_COMPOSE_APP_DISABLE_IP_LOGGING:-false}
SOFFICE: ${DOCKER_COMPOSE_APP_SOFFICE:-null}
TRUST_PROXY: ${DOCKER_COMPOSE_APP_TRUST_PROXY:-true}
restart: always
ports:
- "${DOCKER_COMPOSE_APP_PORT_PUBLISHED:-9001}:${DOCKER_COMPOSE_APP_PORT_TARGET:-9001}"
postgres:
image: postgres:15-alpine
environment:
POSTGRES_DB: ${DOCKER_COMPOSE_POSTGRES_DATABASE:-etherpad}
POSTGRES_PASSWORD: ${DOCKER_COMPOSE_POSTGRES_PASSWORD:-admin}
POSTGRES_PORT: ${DOCKER_COMPOSE_POSTGRES_PORT:-5432}
POSTGRES_USER: ${DOCKER_COMPOSE_POSTGRES_USER:-admin}
PGDATA: /var/lib/postgresql/data/pgdata
restart: always
# Exposing the port is not needed unless you want to access this database instance from the host.
# Be careful when other postgres docker container are running on the same port
# ports:
# - "5432:5432"
volumes:
- postgres_data:/var/lib/postgresql/data
volumes:
postgres_data:
plugins:
etherpad-var:
Requirements
Node.js >= 24.
Windows, macOS, Linux
- Download the latest Node.js runtime from nodejs.org.
- Install pnpm:
npm install -g pnpm(Administrator privileges may be required). - Clone the repository:
git clone -b master - Run
pnpm i - Run
pnpm run build:etherpad - Run
pnpm run prod - Visit
http://localhost:9001in your browser.
Docker container
Find here information on running Etherpad in a container.
Plugins
Etherpad is very customizable through plugins.
Available Plugins
For a list of available plugins, see the plugins site.
Plugin Installation
You can install plugins from the admin web interface (e.g., http://127.0.0.1:9001/admin/plugins).
Alternatively, you can install plugins from the command line:
cd /path/to/etherpad-lite
pnpm run plugins i ep_${plugin_name}
Also see the plugin wiki article.
Suggested Plugins
Run the following command in your Etherpad folder to get all of the features visible in the above demo gif:
pnpm run plugins i \
ep_align \
ep_comments_page \
ep_embedded_hyperlinks2 \
ep_font_color \
ep_headings2 \
ep_markdown \
ep_webrtc
For user authentication, you are encouraged to run an OpenID Connect identity provider (OP) and install the following plugins:
- ep_openid_connect to authenticate against your OP.
- ep_guest to create a "guest" account that has limited access (e.g., read-only access).
- ep_user_displayname to automatically populate each user's displayed name from your OP.
- ep_stable_authorid so that each user's chosen color, display name, comment ownership, etc. is strongly linked to their account.
Upgrade Etherpad
Run the following command in your Etherpad folder to upgrade
- Stop any running Etherpad (manual, systemd ...)
- Get present version
git -P tag --contains
- List versions available
git -P tag --list "v*" --merged
- Select the version
git checkout v2.2.5
git switch -c v2.2.5
- Upgrade Etherpad
./bin/run.sh
- Stop with [CTRL-C]
- Restart your Etherpad service
Next Steps
Tweak the settings
You can modify the settings in settings.json. If you need to handle multiple
settings files, you can pass the path to a settings file to bin/run.sh
using the -s|--settings option: this allows you to run multiple Etherpad
instances from the same installation. Similarly, --credentials can be used to
give a settings override file, --apikey to give a different APIKEY.txt file
and --sessionkey to give a non-default SESSIONKEY.txt. Each configuration
parameter can also be set via an environment variable, using the syntax
"${ENV_VAR}" or "${ENV_VAR:default_value}". For details, refer to
settings.json.template. Once you have access to your /admin section,
settings can be modified through the web browser.
If you are planning to use Etherpad in a production environment, you should use
a dedicated database such as mysql, since the dirtyDB database driver is
only for testing and/or development purposes.
Secure your installation
If you have enabled authentication in users section in settings.json, it is
a good security practice to store hashes instead of plain text passwords in
that file. This is especially advised if you are running a production
installation.
Please install ep_hash_auth plugin
and configure it. If you prefer, ep_hash_auth also gives you the option of
storing the users in a custom directory in the file system, without having to
edit settings.json and restart Etherpad each time.
Customize the style with skin variants
Open http://127.0.0.1:9001/p/test#skinvariantsbuilder in your browser and start playing!
Helpful resources
The wiki is your one-stop resource for Tutorials and How-to's.
Documentation can be found in doc/.
Development
Things you should know
You can debug Etherpad using bin/debugRun.sh.
You can run Etherpad quickly launching bin/fastRun.sh. It's convenient for
developers and advanced users. Be aware that it will skip the dependencies
update, so remember to run bin/installDeps.sh after installing a new
dependency or upgrading version.
If you want to find out how Etherpad's Easysync works (the library that makes
it really realtime), start with this
PDF
(complex, but worth reading).
Contributing
Read our Developer Guidelines
HTTP API
Etherpad is designed to be easily embeddable and provides a HTTP API that allows your web application to manage pads, users and groups. It is recommended to use the available client implementations in order to interact with this API.
OpenAPI (previously swagger) definitions for the API are exposed under
/api/openapi.json.
jQuery plugin
There is a jQuery plugin that helps you to embed Pads into your website.
Plugin Framework
Etherpad offers a plugin framework, allowing you to easily add your own features. By default your Etherpad is extremely light-weight and it's up to you to customize your experience. Once you have Etherpad installed you should visit the plugin page and take control.
Translations / Localizations (i18n / l10n)
Etherpad comes with translations into all languages thanks to the team at TranslateWiki.
If you require translations in plugins please send pull request to each plugin individually.
FAQ
Visit the FAQ.
Get in touch
The official channel for contacting the development team is via the GitHub issues.
For responsible disclosure of vulnerabilities, please write a mail to the maintainers (a.mux@inwind.it and contact@etherpad.org).
Join the official Etherpad Discord Channel.