### One-liner Install and Start (macOS/Linux/WSL)

Source: https://github.com/ether/etherpad/blob/develop/README.md

Installs and immediately starts Etherpad in one command. Requires git and Node.js.

```sh
# macOS / Linux / WSL
ETHERPAD_RUN=1 sh -c "$(curl -fsSL https://raw.githubusercontent.com/ether/etherpad/master/bin/installer.sh)"
```

--------------------------------

### Start Etherpad After Installation

Source: https://github.com/ether/etherpad/blob/develop/README.md

Navigates to the Etherpad directory and starts the production server. Assumes installation is complete.

```sh
cd etherpad-lite && pnpm run prod
```

--------------------------------

### One-liner Install and Start (Windows)

Source: https://github.com/ether/etherpad/blob/develop/README.md

Installs and immediately starts Etherpad in one command using PowerShell. Requires git and Node.js.

```powershell
# Windows
$env:ETHERPAD_RUN=1; irm https://raw.githubusercontent.com/ether/etherpad/master/bin/installer.ps1 | iex
```

--------------------------------

### Provision VM and Install Etherpad

Source: https://github.com/ether/etherpad/blob/develop/docs/superpowers/specs/2026-04-25-auto-update-runbook.md

Sets up a new user, installs necessary packages, clones Etherpad, prepares pnpm, and installs dependencies. This is the initial setup on a disposable VM.

```bash
sudo adduser --system --group --home /srv/etherpad --shell /bin/bash etherpad
sudo apt update && sudo apt install -y git nodejs ca-certificates
# Etherpad's pnpm comes from corepack — Node 22+ ships it.
sudo -u etherpad bash -c '
  cd /srv/etherpad
  git clone https://github.com/ether/etherpad.git current
  cd current
  corepack enable && corepack prepare pnpm@latest-9 --activate
  pnpm install
  pnpm run build:ui
'
```

--------------------------------

### Start Etherpad Service on Windows

Source: https://github.com/ether/etherpad/wiki/How-to-deploy-Etherpad-Lite-as-a-service

After installing Etherpad as a service, you can start it using the 'net start' command.

```bash
net start etherpad
```

--------------------------------

### Install Dependencies and Build Etherpad

Source: https://github.com/ether/etherpad/blob/develop/AGENTS.MD

Installs all project dependencies, builds the admin UI and static assets, and starts the development or production server.

```bash
pnpm install                                    # Install all dependencies
pnpm run build:etherpad                         # Build admin UI and static assets
pnpm --filter ep_etherpad-lite run dev          # Start dev server (port 9001)
pnpm --filter ep_etherpad-lite run prod         # Start production server
```

--------------------------------

### Clean Install and Start Etherpad (Linux/Unix)

Source: https://github.com/ether/etherpad/wiki/Getting-to-know-the-tools-in-bin

Removes the node_modules directory, performs a clean installation of all dependencies, and then manually starts Etherpad on Linux/Unix. A custom settings file can be specified using the --settings flag.

```shell
bin/cleanRun.sh
```

```shell
bin/run.sh --settings thatSettingsFile.json
```

```shell
bin/run.sh --settings /home/etherpad/thatSettingsFile.json
```

--------------------------------

### Etherpad pnpm Install Process

Source: https://github.com/ether/etherpad/blob/develop/snap/README.md

Explains the two-stage pnpm install process during the snap build. It first installs with devDependencies for building, then removes node_modules and installs only production dependencies to optimize build time and avoid interactive prompts.

```bash
`pnpm install --frozen-lockfile --prod=false` first (need devDeps to
build admin/ui/docs), then `rm -rf node_modules && pnpm install --prod
--frozen-lockfile --ignore-scripts` after the build. This is faster
than `pnpm prune --prod`, which is interactive on workspace projects
(prompts "Proceed? (Y/n)" to stdin) and deadlocks under the
non-interactive build environment. See
[nodejs/corepack#612](https://github.com/nodejs/corepack/issues/612)
for the corepack-keyring refresh in step 2.
```

--------------------------------

### Install and Test Local Etherpad Snap Build

Source: https://github.com/ether/etherpad/blob/develop/snap/README.md

Installs a locally built Etherpad snap package using the --dangerous flag, starts the service, and performs a health check. Logs can be viewed with 'sudo snap logs etherpad -f'.

```bash
sudo snap install --dangerous ./etherpad_*.snap
sudo snap start etherpad
curl http://127.0.0.1:9001/health   # → {"status":"pass","releaseId":"X.Y.Z"}
```

--------------------------------

### Manual Smoke Test for Etherpad Lite

Source: https://github.com/ether/etherpad/blob/develop/docs/superpowers/plans/2026-04-25-auto-update-pr1-notify.md

Execute this command to start the Etherpad Lite server and check boot logs for the updater's installation method and tier. The server is expected to start cleanly.

```bash
cd /home/jose/etherpad/etherpad-lite && timeout 15 pnpm dev 2>&1 | tail -40
```

--------------------------------

### Manual Installation Steps (Node.js/pnpm)

Source: https://github.com/ether/etherpad/blob/develop/README.md

Steps for manually installing Etherpad using Node.js and pnpm. Includes cloning the repository, installing dependencies, building, and running.

```shell
npm install -g pnpm
git clone -b master
pnpm i
pnpm run build:etherpad
pnpm run prod
```

--------------------------------

### Quick Install (macOS/Linux/WSL)

Source: https://github.com/ether/etherpad/blob/develop/README.md

Installs Etherpad using a curl command and shell script. Requires git and Node.js.

```sh
curl -fsSL https://raw.githubusercontent.com/ether/etherpad/master/bin/installer.sh | sh
```

--------------------------------

### Start Development Server

Source: https://github.com/ether/etherpad/blob/develop/AGENTS.MD

Start the development server for Etherpad. This is a prerequisite for running frontend and admin tests.

```bash
pnpm --filter ep_etherpad-lite run dev
```

--------------------------------

### Quick Install (Windows PowerShell)

Source: https://github.com/ether/etherpad/blob/develop/README.md

Installs Etherpad using a PowerShell command. Requires git and Node.js.

```powershell
irm https://raw.githubusercontent.com/ether/etherpad/master/bin/installer.ps1 | iex
```

--------------------------------

### Enable and Start Etherpad Service

Source: https://github.com/ether/etherpad/blob/develop/docs/superpowers/specs/2026-04-25-auto-update-runbook.md

Reloads systemd configuration, enables the Etherpad service to start on boot, and starts it immediately. Also tails the journal logs for monitoring.

```bash
sudo systemctl daemon-reload
sudo systemctl enable --now etherpad
journalctl -u etherpad -f &  # tail the log in another terminal
```

--------------------------------

### Install ueberdb2 Next

Source: https://github.com/ether/etherpad/blob/develop/docs/superpowers/plans/2026-04-20-issue-7570-ueberdb2-drivers.md

Install the next version of ueberdb2 for local testing.

```bash
npm install ueberdb2@next
```

--------------------------------

### Start Etherpad Server (Windows)

Source: https://github.com/ether/etherpad/wiki/Creating-a-plugin

Execute this batch file to start the Etherpad server on Windows systems.

```batch
..\..\start.bat
```

--------------------------------

### Install Etherpad Plugin

Source: https://github.com/ether/etherpad/wiki/Creating-a-plugin

Use pnpm to install your Etherpad plugin. Ensure you have pnpm installed and configured.

```bash
pnpm install ep_my_example
```

--------------------------------

### Add Etherpad APT Repository and Install

Source: https://github.com/ether/etherpad/blob/develop/packaging/README.md

Adds the official Etherpad APT repository to your system and installs Etherpad. This is the recommended installation method for Debian/Ubuntu systems.

```sh
curl -fsSL https://etherpad.org/key.asc \
  | sudo gpg --dearmor -o /usr/share/keyrings/etherpad.gpg
echo "deb [signed-by=/usr/share/keyrings/etherpad.gpg] https://etherpad.org/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/etherpad.list
sudo apt update && sudo apt install etherpad
```

--------------------------------

### Start Etherpad Service (Sysvinit)

Source: https://github.com/ether/etherpad/wiki/How-to-deploy-Etherpad-Lite-as-a-service

Command to start the Etherpad Lite service using the sysvinit system.

```bash
service etherpad-lite start
```

--------------------------------

### Install Dependencies and Build Etherpad

Source: https://github.com/ether/etherpad/blob/develop/packaging/README.md

Installs project dependencies using pnpm and builds the Etherpad application. This is a prerequisite for local packaging.

```sh
pnpm install --frozen-lockfile
pnpm run build:etherpad
```

--------------------------------

### pluginInstall

Source: https://github.com/ether/etherpad/blob/develop/doc/api/hooks_server-side.md

Called from `src/static/js/pluginfw/installer.js` when a plugin is installed. It can be used to set up features related to the newly installed plugin.

```APIDOC
## pluginInstall

### Description
Called from `src/static/js/pluginfw/installer.js`. If this hook returns an error, the install function's callback will also receive an error. Useful for adding features when a particular plugin is installed.

### Context
- plugin_name: The name of the plugin being installed.
```

--------------------------------

### Install Suggested Plugins for Etherpad

Source: https://github.com/ether/etherpad/blob/develop/README.md

Run this command in your Etherpad folder to install a set of suggested plugins for enhanced features.

```sh
pnpm run plugins i \
  ep_align \
  ep_comments_page \
  ep_embedded_hyperlinks2 \
  ep_font_color \
  ep_headings2 \
  ep_markdown \
  ep_webrtc
```

--------------------------------

### Install Etherpad Snap

Source: https://github.com/ether/etherpad/blob/develop/snap/README.md

Installs the Etherpad snap package from the Snap Store. The default listen port is 9001 and data is stored in /var/snap/etherpad/common/.

```bash
sudo snap install etherpad
```

--------------------------------

### Manage Etherpad Plugins

Source: https://github.com/ether/etherpad/blob/develop/doc/cli.md

Use the `plugins` tool to manage installed plugins with actions like install, remove, list, and update. Additional sources like GitHub repositories can be specified during installation.

```bash
pnpm run --filter bin plugins <action> [names…]
```

--------------------------------

### Install Etherpad .deb Package Directly

Source: https://github.com/ether/etherpad/blob/develop/packaging/README.md

Downloads the latest Etherpad .deb package and installs it using apt. This method is useful for direct installation or testing specific versions.

```sh
# Stable URL — always points at the most recent release:
curl -fsSL -o etherpad-latest_amd64.deb \
  https://github.com/ether/etherpad/releases/latest/download/etherpad-latest_amd64.deb
sudo apt install ./etherpad-latest_amd64.deb

# Or pin to a specific version:
sudo apt install ./dist/etherpad_<version>_amd64.deb

sudo systemctl start etherpad
curl http://localhost:9001/health
```

--------------------------------

### Install PostgreSQL and pgloader

Source: https://github.com/ether/etherpad/wiki/How-to-migrate-from-MySQL-to-PostgreSQL

Installs the PostgreSQL database system and pgloader for database migration.

```bash
apt install postgresql pgloader
```

--------------------------------

### Start Etherpad Server (Linux)

Source: https://github.com/ether/etherpad/wiki/Creating-a-plugin

Run this command in your terminal to start the Etherpad server on Linux systems.

```bash
$ ../../bin/run.sh
```

--------------------------------

### Install Admin Dependencies and Build UI

Source: https://github.com/ether/etherpad/blob/develop/docs/superpowers/plans/2026-05-08-auto-update-pr2-manual-click.md

Installs necessary dependencies for the admin UI and then builds the UI. This is a prerequisite for running the development server.

```bash
pnpm install   # ensure admin deps in case anything is missing
pnpm --filter admin run build
```

--------------------------------

### Install Dependencies and Configure

Source: https://github.com/ether/etherpad/wiki/Getting-started-writing-tests-for-Etherpad-Lite

Install project dependencies and copy the configuration file. Ensure your SauceLabs username and key are added to config.js.

```bash
bin/installDeps.sh
```

```bash
cp config.tmp.js config.js
```

--------------------------------

### Manage Etherpad Service (Systemd)

Source: https://github.com/ether/etherpad/wiki/How-to-deploy-Etherpad-Lite-as-a-service

Commands to reload systemd configuration, enable the Etherpad service to start on boot, and start the service.

```bash
sudo systemctl daemon-reload
systemctl enable etherpad
systemctl start etherpad
```

--------------------------------

### Example Returns: listPadsOfAuthor()

Source: https://github.com/ether/etherpad/blob/develop/doc/api/http_api.adoc

Provides example return values for listPadsOfAuthor(), showing a list of padIDs or an error for a non-existent authorID.

```json
{code: 0, message:"ok", data: {padIDs: ["g.s8oes9dhwrvt0zif$test", "g.s8oejklhwrvt0zif$foo"]}}
```

```json
{code: 1, message:"authorID does not exist", data: null}
```

--------------------------------

### Start Development Server

Source: https://github.com/ether/etherpad/blob/develop/docs/superpowers/plans/2026-05-18-outdated-notice-redesign.md

Command to start the Etherpad development server on port 9003. This is a prerequisite for running the Playwright tests.

```bash
pnpm --filter ep_etherpad-lite run dev -- --port 9003
```

--------------------------------

### Start Development Server for Smoke Testing

Source: https://github.com/ether/etherpad/blob/develop/docs/superpowers/plans/2026-05-15-issue-7524-swagger-ui-telemetry.md

Starts the development server after configuring privacy settings for smoke testing the banner.

```bash
# In settings.json (or a local override), set privacy.pluginCatalog: false
# Then:
cd src && pnpm dev
```

--------------------------------

### Configure and Enable Etherpad Service (Sysvinit)

Source: https://github.com/ether/etherpad/wiki/How-to-deploy-Etherpad-Lite-as-a-service

Instructions for placing the init script, making it executable, creating a symbolic link if necessary, and enabling the service to start on boot.

```bash
chmod +x /etc/init.d/etherpad-lite
ln -s /your-path-to/etherpad-lite /usr/share/etherpad-lite
update-rc.d etherpad-lite defaults
```

--------------------------------

### Install Latest npm CLI

Source: https://github.com/ether/etherpad/blob/develop/doc/npm-trusted-publishing.md

Ensure you have the latest version of the npm CLI installed globally before proceeding with trusted publishing setup.

```sh
# 1. Make sure npm CLI is recent enough
npm install -g npm@latest
```

--------------------------------

### Set Pad Text using GET (no encoding)

Source: https://github.com/ether/etherpad/blob/develop/doc/api/http_api.adoc

Sets the text content of a pad using a GET request without URL encoding for the text parameter. This is a toy example and may not work reliably for all text.

```bash
curl "http://pad.domain/api/1/setText?apikey=secret&padID=padname&text=this_text_will_NOT_be_encoded_by_curl_use_next_example"
```

--------------------------------

### Example Returns: createGroupPad()

Source: https://github.com/ether/etherpad/blob/develop/doc/api/http_api.adoc

Demonstrates the return values for createGroupPad(), covering successful creation, existing padName, or non-existent groupID.

```json
{code: 0, message:"ok", data: {padID: "g.s8oes9dhwrvt0zif$test"}
```

```json
{code: 1, message:"padName does already exist", data: null}
```

```json
{code: 1, message:"groupID does not exist", data: null}
```

--------------------------------

### Get Caret Document Character Offset

Source: https://github.com/ether/etherpad/blob/develop/doc/api/editorInfo.adoc

Returns the Y offset of the caret starting from the document's origin [x=0,y=0].

```javascript
editorInfo.ace_caretDocChar()
```

--------------------------------

### Install Cypress and Open

Source: https://github.com/ether/etherpad/blob/develop/src/tests/frontend/cypress/README.md

Installs Cypress globally and opens the Cypress test runner from the project's test directory. Ensure you are in the correct directory before running.

```bash
npm i -g cypress
cd src/tests/frontend/cypress/
cypress open
```

--------------------------------

### Preview Trusted Publisher Configuration

Source: https://github.com/ether/etherpad/blob/develop/doc/npm-trusted-publishing.md

Run the setup script with the --dry-run flag to preview the changes without actually modifying any configurations.

```sh
# Or preview without changing anything
bin/setup-trusted-publishers.sh --dry-run
```

--------------------------------

### Get Chat History Invalid Start/End Response

Source: https://github.com/ether/etherpad/blob/develop/doc/api/http_api.adoc

This response indicates an error when retrieving chat history, specifically when the 'start' parameter is invalid or out of range.

```json
{code: 1, message:"start is higher or equal to the current chatHead", data: null}
```

--------------------------------

### Setup Etherpad User and Log Directory (Sysvinit)

Source: https://github.com/ether/etherpad/wiki/How-to-deploy-Etherpad-Lite-as-a-service

Creates a dedicated user for Etherpad Lite and sets up the log directory with appropriate ownership.

```bash
adduser etherpad-lite --system --group --home /var/etherpad
mkdir /var/log/etherpad-lite
chown -R etherpad-lite /var/log/etherpad-lite
```

--------------------------------

### GET /api/version-status

Source: https://github.com/ether/etherpad/blob/develop/docs/superpowers/plans/2026-04-25-auto-update-pr1-notify.md

Retrieves the current version status of Etherpad. This endpoint is public and returns whether the installation is outdated, vulnerable, or null if up-to-date. It does not leak the specific running version.

```APIDOC
## GET /api/version-status

### Description
This public endpoint provides a status indicating if the Etherpad installation is outdated or vulnerable. The response is cached for efficiency.

### Method
GET

### Endpoint
/api/version-status

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **outdated** (string | null) - Indicates the status: 'severe' if more than one major version behind, 'vulnerable' if below the vulnerable version, or null if up-to-date.

#### Response Example
```json
{
  "outdated": null
}
```

```json
{
  "outdated": "severe"
}
```
```

--------------------------------

### Basic Plugin JavaScript Route

Source: https://github.com/ether/etherpad/wiki/Creating-a-plugin

Implement a simple Express route within your plugin's JavaScript file. This example adds a '/apples' GET endpoint that returns HTML.

```javascript
exports.expressCreateServer = function (hook_name, args, cb) {
  args.app.get('/apples', function(req, res) {
    res.send("<em>Abra cadabra</em>");
  });
}
```

--------------------------------

### Get Chat History Example Response

Source: https://github.com/ether/etherpad/blob/develop/doc/api/http_api.adoc

This JSON represents a successful retrieval of chat history, containing an array of message objects. Each message includes text, user ID, time, and user name.

```json
{"code":0,"message":"ok","data":{"messages":[{"text":"foo","userId":"a.foo","time":1359199533759,"userName":"test"},{"text":"bar","userId":"a.foo","time":1359199534622,"userName":"test"}]}}
```

--------------------------------

### Arch Linux Etherpad-Lite init.d script

Source: https://github.com/ether/etherpad/wiki/How-to-deploy-Etherpad-as-a-service

This script manages the Etherpad-Lite service on Arch Linux. It handles starting, stopping, and checking the status of the Etherpad-Lite server. Ensure the USER and HOMEDIR variables match your installation.

```bash
#!/bin/sh

. /etc/rc.conf
. /etc/rc.d/functions

USER="etherpad-lite"
HOMEDIR="/opt/etherpad-lite"
PID=/run/etherpad-lite.pid
LOG=/var/log/etherpad-lite.log

case "$1" in
        'start')
                # Start Etherpad.
                cd $HOMEDIR
                exec nohup sudo -u $USER bin/run.sh > $LOG 2>$1 < /dev/null &

                # Wait five seconds for the node.js server to start up.
                sleep 5

                # Store the PID in a file.
                ps ax | grep [s]erver.js | awk '{print $1}' > $PID
                ;;
        'stop')
                # Terminate Etherpad-Lite.
                kill `cat $PID`
                rm -f $PID

                ;;
        'status')
                ps ax | grep [n]ode
                ;;
        *)
                echo "USAGE: $0 {start|stop|status}"
                exit 0
        esac                                                                                                                                                                                                                                                                                      
```

--------------------------------

### Example: Setting up loginAs helper for tests

Source: https://github.com/ether/etherpad/blob/develop/docs/superpowers/plans/2026-05-18-outdated-notice-redesign.md

Provides an example implementation for the `loginAs` helper function, which is crucial for authenticating users in end-to-end tests. This snippet shows how to integrate with Etherpad's session management to create a valid session cookie.

```typescript
import {sessionMiddleware} from '../../node/hooks/express';
import crypto from 'node:crypto';

// Returns a Cookie header value bound to a session whose user.author === authorId.
export const loginAs = async (authorId: string): Promise<string> => {
  // Implementation: introspect sessionMiddleware to get the store, call store.set
  // with a freshly generated sid, return `express_sid=s%3A<sid>...` cookie.
  // If introspection is awkward, expose the express-session store from
  // express.ts so tests can import it directly.
  // ... (concrete implementation depends on the tree's session config)
};
```

--------------------------------

### GET /admin/update/status

Source: https://github.com/ether/etherpad/blob/develop/docs/superpowers/plans/2026-04-25-auto-update-pr1-notify.md

Provides detailed update status information for administrators. This endpoint requires admin authentication and returns details about the current version, latest available version, last check time, installation method, and update policy.

```APIDOC
## GET /admin/update/status

### Description
This admin-only endpoint provides comprehensive details about the Etherpad update status, including version information, installation method, and update policy.

### Method
GET

### Endpoint
/admin/update/status

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **currentVersion** (string) - The currently installed Etherpad version.
- **latest** (object | null) - Information about the latest available version, including `version`, `tag`, `body`, `publishedAt`, `prerelease`, and `htmlUrl`.
- **lastCheckAt** (number) - Timestamp of the last update check.
- **installMethod** (string) - The detected installation method (e.g., 'binary', 'source').
- **tier** (string) - The update tier configured for the installation.
- **policy** (object | null) - The evaluated update policy based on current settings.
- **vulnerableBelow** (string | null) - The version below which the installation is considered vulnerable.

#### Response Example
```json
{
  "currentVersion": "1.7.0",
  "latest": {
    "version": "1.8.0",
    "tag": "v1.8.0",
    "body": "Bug fixes and improvements.",
    "publishedAt": "2023-01-01T10:00:00Z",
    "prerelease": false,
    "htmlUrl": "https://github.com/ether/etherpad-lite/releases/tag/v1.8.0"
  },
  "lastCheckAt": 1678886400000,
  "installMethod": "source",
  "tier": "stable",
  "policy": {
    "state": "upgrade",
    "message": "An upgrade is available."
  },
  "vulnerableBelow": null
}
```
```

--------------------------------

### Etherpad Local Docker Compose Verification

Source: https://github.com/ether/etherpad/blob/develop/docs/superpowers/specs/2026-04-20-issue-7570-ueberdb2-drivers-design.md

Command to start Etherpad using Docker Compose for local verification, specifically testing a MySQL database setup. This command ensures the application can successfully connect to and utilize the specified database.

```bash
docker compose up
```

--------------------------------

### Etherpad Lite Init Script (Gentoo/Slackware Style)

Source: https://github.com/ether/etherpad/wiki/How-to-deploy-Etherpad-Lite-as-a-service

This init script is used for starting and stopping the Etherpad Lite service. It requires 'net' and 'mysql' dependencies and should start after 'apache2'.

```bash
depend() {
        need net mysql
        after apache2
}

start() {
        ebegin "Starting ${RC_SVCNAME}"
                start-stop-daemon -S -m --pidfile ${PIDFILE} -x ${NODE} -u ${USER} -d "${ETHERPATH}" -b -- ${ARGS}
        eend $?
}

stop() {
        ebegin "Stopping ${RC_SVCNAME}"
                start-stop-daemon -K -x ${NODE} -u ${USER} -d "${ETHERPATH}" 
        eend $?
}
```

--------------------------------

### Test HTML to PDF Buffer Conversion

Source: https://github.com/ether/etherpad/blob/develop/docs/superpowers/plans/2026-05-08-native-docx-pdf-export-import.md

This test verifies that the htmlToPdfBuffer function produces a valid PDF buffer. It checks if the output is a Buffer, has a reasonable size, and starts with the expected '%PDF-' magic number. Requires pdfkit and htmlparser2 to be installed.

```typescript
  describe('htmlToPdfBuffer', function () {
    let htmlToPdfBuffer: (html: string) => Promise<Buffer>;

    before(function () {
      try {
        require.resolve('pdfkit');
        require.resolve('htmlparser2');
      } catch {
        this.skip();
        return;
      }
      htmlToPdfBuffer = require('../../../node/utils/ExportPdfNative').htmlToPdfBuffer;
    });

    it('produces a buffer starting with %PDF-', async function () {
      const buf = await htmlToPdfBuffer('<p>hello world</p>');
      assert.ok(Buffer.isBuffer(buf), 'must return Buffer');
      assert.ok(buf.length > 100, `buffer suspiciously small: ${buf.length} bytes`);
      assert.strictEqual(buf.slice(0, 5).toString('ascii'), '%PDF-');
    });
  });
```

--------------------------------

### GET /admin/update/status

Source: https://github.com/ether/etherpad/blob/develop/docs/superpowers/plans/2026-05-08-issue-7693-admin-openapi.md

Fetches the cached update state, including current version, latest known release, install method, tier, policy verdict, and vulnerability directives. This endpoint is primarily used for the admin UI banner and update page.

```APIDOC
## GET /admin/update/status

### Description
Fetch updater status for the admin UI banner and update page. Returns the cached update state (current version, latest known release, install method, tier, policy verdict, and vulnerability directives). Open by default; gated to authenticated admin sessions when updates.requireAdminForStatus=true in settings.

### Method
GET

### Endpoint
/admin/update/status

### Parameters

### Request Body
None

### Response
#### Success Response (200)
- **currentVersion** (string) - The current version of the software.
- **latest** (object | null) - Information about the latest available release.
- **lastCheckAt** (string, format: date-time | null) - The timestamp of the last update check.
- **installMethod** (string, enum: ['auto', 'git', 'docker', 'npm', 'managed']) - The method used for installation.
- **tier** (string, enum: ['off', 'notify', 'manual', 'auto', 'autonomous']) - The update tier configuration.
- **policy** (object | null) - The verdict of the update policy.
- **vulnerableBelow** (array) - A list of vulnerability directives.

#### Response Example
{
  "currentVersion": "1.0.0",
  "latest": {
    "version": "1.1.0",
    "releaseDate": "2023-01-01T10:00:00Z"
  },
  "lastCheckAt": "2023-01-01T09:00:00Z",
  "installMethod": "npm",
  "tier": "notify",
  "policy": {
    "verdict": "allow",
    "reason": "No critical vulnerabilities found"
  },
  "vulnerableBelow": []
}

#### Error Response (401)
Description: requireAdminForStatus is set and no admin session exists.

#### Error Response (403)
Description: requireAdminForStatus is set and the session user is not an admin.
```

--------------------------------

### Build and Start Etherpad with Docker Compose (Development)

Source: https://github.com/ether/etherpad/blob/develop/doc/docker.adoc

Builds and starts the Etherpad Docker container using Docker Compose with development settings. Assumes `.env.default` has been copied to `.env` and configured.

```bash
docker compose up -d
```

--------------------------------

### Admin OpenAPI Schema for Update Status

Source: https://github.com/ether/etherpad/blob/develop/docs/superpowers/plans/2026-05-08-issue-7693-admin-openapi.md

Defines the properties for the update status, including current version, latest release information, last check time, installation method, tier, policy verdict, and vulnerability directives. This schema is used for the GET /admin/update/status endpoint.

```json
properties: {
          currentVersion: {type: 'string'},
          latest: {
            allOf: [{$ref: '#/components/schemas/ReleaseInfo'}],
            nullable: true,
          },
          lastCheckAt: {type: 'string', format: 'date-time', nullable: true},
          installMethod: {
            type: 'string',
            enum: ['auto', 'git', 'docker', 'npm', 'managed'],
          },
          tier: {
            type: 'string',
            enum: ['off', 'notify', 'manual', 'auto', 'autonomous'],
          },
          policy: {
            allOf: [{$ref: '#/components/schemas/PolicyResult'}],
            nullable: true,
          },
          vulnerableBelow: {
            type: 'array',
            items: {$ref: '#/components/schemas/VulnerableBelowDirective'},
          },
        },
      },
    }
```

--------------------------------

### Install Dependencies for UeberDB

Source: https://github.com/ether/etherpad/blob/develop/docs/superpowers/plans/2026-04-20-issue-7570-ueberdb2-drivers.md

Install the project dependencies for the ueberDB repository using pnpm. Ensure no unusual errors occur during installation.

```bash
cd /home/jose/etherpad/ueberDB && pnpm install
```

--------------------------------

### Example Return for listAllPads

Source: https://github.com/ether/etherpad/blob/develop/doc/api/http_api.adoc

Lists all available pad IDs on the Etherpad instance.

```json
{code: 0, message:"ok", data: {padIDs: ["testPad", "thePadsOfTheOthers"]}}
```

--------------------------------

### Fast Run Etherpad

Source: https://github.com/ether/etherpad/blob/develop/README.md

Launches Etherpad quickly, skipping dependency updates. Recommended for developers. Remember to run bin/installDeps.sh after adding new dependencies.

```sh
bin/fastRun.sh
```

--------------------------------

### Install [plugin_name] Plugin

Source: https://github.com/ether/etherpad/blob/develop/bin/plugins/lib/README.md

Install the plugin from the Etherpad working directory using npm. Ensure to use the --no-save and --legacy-peer-deps flags.

```shell
npm install --no-save --legacy-peer-deps [plugin_name]
```

--------------------------------

### Verify Dependency Removal and Clean Install

Source: https://github.com/ether/etherpad/blob/develop/docs/superpowers/plans/2026-05-15-issue-7524-swagger-ui-telemetry.md

After making changes, run `pnpm install` to ensure a clean installation and use `grep` to verify that `swagger-ui` is no longer present in the lock file.

```bash
pnpm install
grep -c "swagger-ui" pnpm-lock.yaml
```

--------------------------------

### createServer

Source: https://github.com/ether/etherpad/blob/develop/doc/api/hooks_server-side.md

Invoked via `aCallAll` once during Etherpad startup, after the HTTP server has been created. Use it to run any plugin initialisation.

```APIDOC
## `createServer`

### Description
Invoked via `aCallAll` once during Etherpad startup, after the HTTP server has been created. Use it to run any plugin initialisation that needs to happen when the server comes up.
```

--------------------------------

### Install Etherpad Plugin Manually

Source: https://github.com/ether/etherpad/wiki/Available-Plugins

Use this command to manually install a plugin. The `--no-save` and `--legacy-peer-deps` arguments are necessary to work around npm quirks. Restart Etherpad after installation.

```sh
cd /path/to/etherpad-lite
# The --no-save and --legacy-peer-deps arguments are necessary to work
# around npm quirks.
pnpm run plugins install  ep_$plugin_name
```

--------------------------------

### Crash-loop Guard Scenario Setup

Source: https://github.com/ether/etherpad/blob/develop/docs/superpowers/specs/2026-04-25-auto-update-runbook.md

Prepares the environment to test the crash-loop guard by checking out a specific version and indicating an intention to introduce a startup error during the update window.

```bash
# As etherpad user:
git checkout v2.7.2
# Apply to v2.7.3, but during the apply window introduce a startup error:
```

--------------------------------

### Etherpad Plugin Installer Symlink Explanation

Source: https://github.com/ether/etherpad/blob/develop/snap/README.md

Explains the necessity of the 'var/' symlink in the Etherpad snap. This symlink redirects writes from the read-only $SNAP/var/ to the writable $SNAP_COMMON/etherpad-app-var/ directory, allowing the plugin installer to function correctly.

```bash
Etherpad's plugin installer
(`src/static/js/pluginfw/installer.ts`) writes
`installed_plugins.json` via `__dirname`-relative paths, which resolve
to absolute paths inside `$SNAP` — read-only squashfs. Snap layouts
can't intercept paths inside `$SNAP`, so we replace the shipped `var/`
directory with a **symlink** at build time pointing to
`/var/snap/etherpad/common/etherpad-app-var/` (created by the wrapper
on first run). The kernel transparently follows the symlink to writable
storage that survives `snap refresh`.
```