Service: Etherpad Lite - EyevinnOSC/community GitHub Wiki

Etherpad Lite

Etherpad Lite (serviceId ether-etherpad-lite, catalog page) is an open source real-time collaborative document editor. It is a long-running service instance with up to 10 GiB of storage per instance. License: Apache-2.0.

What it can do

  • Let multiple users edit the same pad simultaneously, with each contributor's text shown in a different color.
  • Give lightweight, self-hosted collaborative writing without sending documents to third-party services.
  • Share pads by link; anyone with the pad URL can edit without signing in.
  • Provide an admin panel at /admin.

Creating an instance

By default Etherpad uses the embedded dirtyDB file store, which is suitable for evaluation only. For persistent or production use, give it a PostgreSQL database.

  1. Create PostgreSQL first (serviceId birme-osc-postgresql) with create-service-instance, config { "name": "padsdb", "PostgresPassword": "{{secrets.pgpwd}}" } (create the secret with create-service-secret first). Confirm it is running and read its host and port with describe-service-instance.
  2. Store the connection string as a secret named dburl (serviceId: "ether-etherpad-lite"). Format: postgres://postgres:<password>@<host>:<port>/postgres.
  3. Create Etherpad Lite:
{ "name": "mypad", "DatabaseUrl": "{{secrets.dburl}}" }

Without a database (evaluation only): { "name": "mypad" }.

  1. Verify with wait-for-service-ready or get-instance-status; get the URL with describe-service-instance.

Options

Option Required Type Meaning
name Yes string Name of the instance. Alphanumeric, at most 20 characters.
DatabaseUrl No string, sensitive Connection URL of an external database for Etherpad. When omitted, the embedded dirtyDB driver is used (not for production). Contains the database password, so keep it in a secret and pass {{secrets.NAME}}.

{{secrets.NAME}} must be the entire field value. Overwriting a secret does not restart a running instance.

PostgreSQL options (birme-osc-postgresql)

Option Required Type Meaning
name Yes string Instance name.
PostgresPassword Yes string, sensitive Password of the PostgreSQL superuser.
PostgresUser No string Superuser name. Defaults to postgres.
PostgresDb No string Default database to create at start. Defaults to the same name as the user.
PostgresInitDbArgs No string Extra arguments passed to initdb.
PostgresInitDbSql No string SQL commands or script content run at initialization.

Using the instance

Open the instance URL, enter a name in the New Pad field and share the pad URL with collaborators. The admin panel is at /admin; the previous documentation for this service lists the default credentials as admin / admin, so change the admin password immediately via the admin settings.

Example with the OSC CLI:

# Without a database (evaluation only)
npx @osaas/cli create ether-etherpad-lite mypad

# With PostgreSQL
npx @osaas/cli create ether-etherpad-lite mypad \
  -o DatabaseUrl="{{secrets.dburl}}"

Limitations

  • Storage is limited to 10 GiB per instance.
  • dirtyDB (no DatabaseUrl) is not suitable for production.

Resources

⚠️ **GitHub.com Fallback** ⚠️