mirrors/etherpad-lite
1
0
Fork 0
mirror of https://github.com/ether/etherpad-lite.git synced 2026-05-05 20:26:49 +02:00
Code Issues Projects Releases Wiki Activity

feat: add one-line installer script (#7466) (#7485)

Browse Source 
* feat: add one-line installer script (#7466)

Adds bin/installer.sh, a small POSIX shell script that:
- Verifies prerequisites (git, Node.js >= 18)
- Installs pnpm globally if missing (with sudo fallback)
- Clones etherpad-lite (configurable branch / dir)
- Runs `pnpm i` and `pnpm run build:etherpad`
- Optionally starts Etherpad if ETHERPAD_RUN=1

Users can now install Etherpad with a single command:

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

README updated to feature the one-liner above the existing
Docker-Compose / manual install instructions.

Closes #7466

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* test: add installer-test workflow + Windows PowerShell installer

- bin/installer.ps1: PowerShell port of installer.sh so the one-liner
  also works on Windows via 'irm ... | iex'.
- .github/workflows/installer-test.yml: end-to-end CI that runs each
  installer against the PR's own commit (via ETHERPAD_REPO/BRANCH env
  vars), verifies clone + node_modules + admin SPA artifacts, and
  smoke-tests by starting Etherpad and curling /api. Runs on
  ubuntu-latest, macos-latest, and windows-latest. Includes a
  shellcheck job for installer.sh.
- README: feature the Windows one-liner alongside the POSIX one.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* test: fix windows smoke test - wrap pnpm in cmd /c

Start-Process can't run pnpm.cmd directly ("not a valid Win32 application").
Wrap it via cmd.exe /c instead, and bump the wait window to 90s for slower
Windows runners. Also dump stderr alongside stdout when the smoke test
fails for easier debugging.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: address Qodo review on installer (#7485)

Two correctness issues caught by Qodo:

1. Node version mismatch: installer required Node >= 18, but the repo's
   engines.node is >= 20. Bump REQUIRED_NODE_MAJOR to 20 in both shell
   and PowerShell installers, and update the README's quick-install
   prerequisite and Requirements section to match.

2. Branch ignored for existing checkouts: when ETHERPAD_DIR already
   existed, the script ran 'git pull --ff-only' on whatever branch
   happened to be checked out, ignoring ETHERPAD_BRANCH and never
   verifying ETHERPAD_REPO. The existing-dir path now:
   - validates the remote URL matches ETHERPAD_REPO
   - refuses to clobber uncommitted changes (excluding pnpm-lock.yaml,
     which pnpm i rewrites during install)
   - fetches with --tags --prune
   - checks out ETHERPAD_BRANCH as a branch or detaches at it as a tag
   - prints the resulting commit short SHA for clarity

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
John McLear 2026-04-07 17:10:22 +01:00 committed by GitHub
parent 7011961423
commit 301ae4df2c
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 491 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

165
.github/workflows/installer-test.yml vendored Normal file
View File

@ -0,0 +1,165 @@
name: "Installer test"
# Exercises bin/installer.sh and bin/installer.ps1 end-to-end so the
# one-line install paths in the README stay working.
on:
push:
paths:
- "bin/installer.sh"
- "bin/installer.ps1"
- ".github/workflows/installer-test.yml"
pull_request:
paths:
- "bin/installer.sh"
- "bin/installer.ps1"
- ".github/workflows/installer-test.yml"
permissions:
contents: read
jobs:
shellcheck:
name: shellcheck
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- name: Run shellcheck on installer.sh
run: |
sudo apt-get update
sudo apt-get install -y shellcheck
shellcheck bin/installer.sh
installer-posix:
name: end-to-end install (${{ matrix.os }})
runs-on: ${{ matrix.os }}
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, macos-latest]
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v6
with:
node-version: 22
- name: Pre-install pnpm (avoid sudo prompt in the installer)
run: npm install -g pnpm
- name: Run bin/installer.sh against this commit
env:
ETHERPAD_DIR: ${{ runner.temp }}/etherpad-installer-test
ETHERPAD_REPO: ${{ github.server_url }}/${{ github.repository }}.git
ETHERPAD_BRANCH: ${{ github.head_ref || github.ref_name }}
NO_COLOR: "1"
run: sh ./bin/installer.sh
- name: Verify clone + dependencies + build artifacts
shell: bash
env:
ETHERPAD_DIR: ${{ runner.temp }}/etherpad-installer-test
run: |
set -eux
test -d "$ETHERPAD_DIR/.git"
test -f "$ETHERPAD_DIR/package.json"
test -d "$ETHERPAD_DIR/node_modules"
test -d "$ETHERPAD_DIR/src/node_modules"
# build:etherpad copies the admin SPA into src/templates/admin
test -f "$ETHERPAD_DIR/src/templates/admin/index.html"
- name: Smoke test - start Etherpad and curl /api
shell: bash
env:
ETHERPAD_DIR: ${{ runner.temp }}/etherpad-installer-test
run: |
set -eu
cd "$ETHERPAD_DIR"
pnpm run prod >/tmp/etherpad.log 2>&1 &
PID=$!
# Wait up to 60s for the API to come up.
ok=0
for i in $(seq 1 60); do
if curl -fsS http://localhost:9001/api >/dev/null 2>&1; then
echo "Etherpad answered on /api after ${i}s"
ok=1
break
fi
sleep 1
done
if [ "$ok" != "1" ]; then
echo "Etherpad did not start within 60s. Last 200 lines of log:" >&2
tail -200 /tmp/etherpad.log >&2 || true
kill "$PID" 2>/dev/null || true
exit 1
fi
kill "$PID" 2>/dev/null || true
wait "$PID" 2>/dev/null || true
installer-windows:
name: end-to-end install (windows-latest)
runs-on: windows-latest
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v6
with:
node-version: 22
- name: Pre-install pnpm
run: npm install -g pnpm
- name: Run bin/installer.ps1 against this commit
shell: pwsh
env:
ETHERPAD_DIR: ${{ runner.temp }}\etherpad-installer-test
ETHERPAD_REPO: ${{ github.server_url }}/${{ github.repository }}.git
ETHERPAD_BRANCH: ${{ github.head_ref || github.ref_name }}
NO_COLOR: "1"
run: ./bin/installer.ps1
- name: Verify clone + dependencies + build artifacts
shell: pwsh
env:
ETHERPAD_DIR: ${{ runner.temp }}\etherpad-installer-test
run: |
if (-not (Test-Path "$env:ETHERPAD_DIR\.git")) { throw '.git missing' }
if (-not (Test-Path "$env:ETHERPAD_DIR\package.json")) { throw 'package.json missing' }
if (-not (Test-Path "$env:ETHERPAD_DIR\node_modules")) { throw 'node_modules missing' }
if (-not (Test-Path "$env:ETHERPAD_DIR\src\node_modules")) { throw 'src/node_modules missing' }
if (-not (Test-Path "$env:ETHERPAD_DIR\src\templates\admin\index.html")) { throw 'admin SPA missing' }
- name: Smoke test - start Etherpad and curl /api
shell: pwsh
env:
ETHERPAD_DIR: ${{ runner.temp }}\etherpad-installer-test
run: |
Push-Location $env:ETHERPAD_DIR
$logPath = Join-Path $env:RUNNER_TEMP 'etherpad.log'
# pnpm on Windows is a .cmd shim, which Start-Process can't run
# directly — wrap it in cmd.exe.
$proc = Start-Process -FilePath cmd.exe `
-ArgumentList '/c','pnpm','run','prod' `
-RedirectStandardOutput $logPath `
-RedirectStandardError "$logPath.err" `
-PassThru -NoNewWindow
$ok = $false
for ($i = 1; $i -le 90; $i++) {
try {
Invoke-WebRequest -UseBasicParsing -Uri http://localhost:9001/api -TimeoutSec 2 | Out-Null
Write-Host "Etherpad answered on /api after ${i}s"
$ok = $true
break
} catch { Start-Sleep -Seconds 1 }
}
if (-not $ok) {
Write-Host 'Etherpad did not start within 90s. Last 200 lines of log (stdout):'
if (Test-Path $logPath) { Get-Content $logPath -Tail 200 }
Write-Host 'Last 200 lines of stderr:'
if (Test-Path "$logPath.err") { Get-Content "$logPath.err" -Tail 200 }
Stop-Process -Id $proc.Id -Force -ErrorAction SilentlyContinue
Pop-Location
exit 1
}
Stop-Process -Id $proc.Id -Force -ErrorAction SilentlyContinue
Pop-Location

39
README.md
View File

@ -43,6 +43,43 @@ We're looking for maintainers and have some funding available. Please contact J
## Installation
### Quick install (one-liner)
The fastest way to get Etherpad running. Requires `git` and Node.js >= 20.
**macOS / Linux / WSL:**
```sh
curl -fsSL https://raw.githubusercontent.com/ether/etherpad-lite/master/bin/installer.sh | sh
```
**Windows (PowerShell):**
```powershell
irm https://raw.githubusercontent.com/ether/etherpad-lite/master/bin/installer.ps1 | iex
```
Both installers clone Etherpad into `./etherpad-lite`, install dependencies, and
build the frontend. When the installer finishes, run:
```sh
cd etherpad-lite && pnpm run prod
```
Then open <http://localhost:9001>.
To install and start in one go:
```sh
# macOS / Linux / WSL
ETHERPAD_RUN=1 sh -c "$(curl -fsSL https://raw.githubusercontent.com/ether/etherpad-lite/master/bin/installer.sh)"
```
```powershell
# Windows
$env:ETHERPAD_RUN=1; irm https://raw.githubusercontent.com/ether/etherpad-lite/master/bin/installer.ps1 | iex
```
### Docker-Compose
```yaml
@ -100,7 +137,7 @@ volumes:
### Requirements
[Node.js](https://nodejs.org/).
[Node.js](https://nodejs.org/) >= 20.
### Windows, macOS, Linux

155
bin/installer.ps1 Normal file
View File

@ -0,0 +1,155 @@
# Etherpad one-line installer for Windows (PowerShell).
#
# Usage:
# irm https://raw.githubusercontent.com/ether/etherpad-lite/master/bin/installer.ps1 | iex
#
# Optional environment variables:
# $env:ETHERPAD_DIR Directory to install into (default: .\etherpad-lite)
# $env:ETHERPAD_BRANCH Branch / tag to clone (default: master)
# $env:ETHERPAD_REPO Repo URL (default: https://github.com/ether/etherpad-lite.git)
# $env:ETHERPAD_RUN If "1", start Etherpad after install
# $env:NO_COLOR If set, disables coloured output
#Requires -Version 5.1
$ErrorActionPreference = 'Stop'
# ---------- pretty output ----------
$useColor = -not $env:NO_COLOR
function Write-Step([string]$msg) {
if ($useColor) { Write-Host "==> $msg" -ForegroundColor Green }
else { Write-Host "==> $msg" }
}
function Write-Warn([string]$msg) {
if ($useColor) { Write-Host "==> $msg" -ForegroundColor Yellow }
else { Write-Host "==> $msg" }
}
function Write-Fatal([string]$msg) {
if ($useColor) { Write-Host "==> $msg" -ForegroundColor Red }
else { Write-Host "==> $msg" }
exit 1
}
function Test-Cmd([string]$name) {
return [bool](Get-Command $name -ErrorAction SilentlyContinue)
}
# ---------- defaults ----------
$EtherpadDir = if ($env:ETHERPAD_DIR) { $env:ETHERPAD_DIR } else { 'etherpad-lite' }
$EtherpadBranch = if ($env:ETHERPAD_BRANCH) { $env:ETHERPAD_BRANCH } else { 'master' }
$EtherpadRepo = if ($env:ETHERPAD_REPO) { $env:ETHERPAD_REPO } else { 'https://github.com/ether/etherpad-lite.git' }
$RequiredNodeMajor = 20
Write-Step 'Etherpad installer'
# ---------- prerequisite checks ----------
if (-not (Test-Cmd git)) {
Write-Fatal 'git is required but not installed. See https://git-scm.com/download/win'
}
if (-not (Test-Cmd node)) {
Write-Fatal "Node.js is required (>= $RequiredNodeMajor). Install it from https://nodejs.org"
}
$nodeMajor = [int](node -p 'process.versions.node.split(".")[0]')
if ($nodeMajor -lt $RequiredNodeMajor) {
$nodeVer = (node --version)
Write-Fatal "Node.js >= $RequiredNodeMajor required. You have $nodeVer."
}
if (-not (Test-Cmd pnpm)) {
Write-Step 'Installing pnpm globally'
if (-not (Test-Cmd npm)) {
Write-Fatal "npm not found. Install Node.js >= $RequiredNodeMajor."
}
npm install -g pnpm
if ($LASTEXITCODE -ne 0) {
Write-Fatal 'Failed to install pnpm. Install it manually: https://pnpm.io/installation'
}
if (-not (Test-Cmd pnpm)) {
Write-Fatal 'pnpm install reported success but pnpm is still not on PATH. Open a new shell and re-run.'
}
}
# ---------- clone ----------
if (Test-Path $EtherpadDir) {
if (Test-Path (Join-Path $EtherpadDir '.git')) {
Write-Warn "$EtherpadDir already exists; updating to $EtherpadBranch."
Push-Location $EtherpadDir
try {
# Verify the existing checkout points at the expected remote.
$existingRemote = (git remote get-url origin 2>$null)
if ($existingRemote -and $existingRemote -ne $EtherpadRepo) {
Write-Fatal "$EtherpadDir is checked out from '$existingRemote', expected '$EtherpadRepo'. Refusing to overwrite."
}
# Refuse to clobber meaningful local changes. pnpm-lock.yaml is
# excluded because `pnpm i` rewrites it during installation,
# which would otherwise make every re-run of the installer fail.
$statusLines = (git status --porcelain) -split "`n" |
Where-Object { $_ -and ($_ -notmatch '\bpnpm-lock\.yaml$') }
if ($statusLines) {
$statusLines | ForEach-Object { Write-Host $_ }
Write-Fatal "$EtherpadDir has uncommitted changes. Commit/stash them or remove the directory."
}
git fetch --tags --prune origin
if ($LASTEXITCODE -ne 0) { Write-Fatal "git fetch failed in $EtherpadDir" }
# Discard any pnpm-lock.yaml changes from a prior pnpm install
# so the subsequent checkout doesn't refuse to overwrite.
git checkout -- pnpm-lock.yaml 2>$null
# Switch to the requested branch / tag and fast-forward to it.
git show-ref --verify --quiet "refs/remotes/origin/$EtherpadBranch"
$isBranch = ($LASTEXITCODE -eq 0)
git show-ref --verify --quiet "refs/tags/$EtherpadBranch"
$isTag = ($LASTEXITCODE -eq 0)
if ($isBranch) {
git checkout -B $EtherpadBranch "origin/$EtherpadBranch"
if ($LASTEXITCODE -ne 0) { Write-Fatal "git checkout $EtherpadBranch failed" }
} elseif ($isTag) {
git checkout --detach "refs/tags/$EtherpadBranch"
if ($LASTEXITCODE -ne 0) { Write-Fatal "git checkout tag $EtherpadBranch failed" }
} else {
Write-Fatal "Branch or tag '$EtherpadBranch' not found on origin."
}
$installedRev = (git rev-parse --short HEAD)
Write-Step "Updated $EtherpadDir to $EtherpadBranch @ $installedRev"
} finally {
Pop-Location
}
} else {
Write-Fatal "$EtherpadDir exists and is not a git checkout. Aborting."
}
} else {
Write-Step "Cloning Etherpad ($EtherpadBranch) into $EtherpadDir"
git clone --depth 1 --branch $EtherpadBranch $EtherpadRepo $EtherpadDir
if ($LASTEXITCODE -ne 0) { Write-Fatal 'git clone failed.' }
}
Push-Location $EtherpadDir
# ---------- install + build ----------
Write-Step 'Installing dependencies (pnpm i)'
pnpm i
if ($LASTEXITCODE -ne 0) { Pop-Location; Write-Fatal 'pnpm i failed.' }
Write-Step 'Building Etherpad (pnpm run build:etherpad)'
pnpm run build:etherpad
if ($LASTEXITCODE -ne 0) { Pop-Location; Write-Fatal 'pnpm run build:etherpad failed.' }
# ---------- done ----------
Write-Host ''
if ($useColor) { Write-Host "🎉 Etherpad is installed in $EtherpadDir" -ForegroundColor Green }
else { Write-Host "Etherpad is installed in $EtherpadDir" }
Write-Host 'To start Etherpad:'
Write-Host " cd $EtherpadDir; pnpm run prod"
Write-Host 'Then open http://localhost:9001 in your browser.'
Write-Host ''
if ($env:ETHERPAD_RUN -eq '1') {
Write-Step 'Starting Etherpad on http://localhost:9001'
pnpm run prod
}

133
bin/installer.sh Executable file
View File

@ -0,0 +1,133 @@
#!/bin/sh
#
# Etherpad one-line installer.
#
# Usage:
# curl -fsSL https://raw.githubusercontent.com/ether/etherpad-lite/master/bin/installer.sh | sh
#
# Optional environment variables:
# ETHERPAD_DIR Directory to install into (default: ./etherpad-lite)
# ETHERPAD_BRANCH Branch / tag to clone (default: master)
# ETHERPAD_RUN If set to 1, start Etherpad after install
# NO_COLOR If set, disables coloured output
set -eu
# ---------- pretty output ----------
if [ -z "${NO_COLOR:-}" ] && [ -t 1 ]; then
bold=$(printf '\033[1m')
green=$(printf '\033[32m')
red=$(printf '\033[31m')
yellow=$(printf '\033[33m')
reset=$(printf '\033[0m')
else
bold=''; green=''; red=''; yellow=''; reset=''
fi
step() { printf '%s==>%s %s%s%s\n' "$green" "$reset" "$bold" "$*" "$reset"; }
warn() { printf '%s==>%s %s\n' "$yellow" "$reset" "$*" >&2; }
fatal() { printf '%s==>%s %s\n' "$red" "$reset" "$*" >&2; exit 1; }
is_cmd() { command -v "$1" >/dev/null 2>&1; }
# ---------- defaults ----------
ETHERPAD_DIR="${ETHERPAD_DIR:-etherpad-lite}"
ETHERPAD_BRANCH="${ETHERPAD_BRANCH:-master}"
ETHERPAD_REPO="${ETHERPAD_REPO:-https://github.com/ether/etherpad-lite.git}"
REQUIRED_NODE_MAJOR=20
step "Etherpad installer"
# ---------- prerequisite checks ----------
is_cmd git || fatal "git is required but not installed. See https://git-scm.com/downloads"
if ! is_cmd node; then
fatal "Node.js is required (>= ${REQUIRED_NODE_MAJOR}). Install it from https://nodejs.org"
fi
NODE_MAJOR=$(node -p "process.versions.node.split('.')[0]")
if [ "$NODE_MAJOR" -lt "$REQUIRED_NODE_MAJOR" ]; then
fatal "Node.js >= ${REQUIRED_NODE_MAJOR} required. You have $(node --version)."
fi
if ! is_cmd pnpm; then
step "Installing pnpm globally"
is_cmd npm || fatal "npm not found. Install Node.js >= ${REQUIRED_NODE_MAJOR}."
if ! npm install -g pnpm 2>/dev/null; then
warn "Global npm install requires elevated permissions; retrying with sudo."
is_cmd sudo || fatal "sudo not available. Install pnpm manually: https://pnpm.io/installation"
sudo npm install -g pnpm || \
fatal "Failed to install pnpm. Install it manually: https://pnpm.io/installation"
fi
is_cmd pnpm || \
fatal "pnpm install reported success but pnpm is still not on PATH. Open a new shell and re-run."
fi
# ---------- clone ----------
if [ -d "$ETHERPAD_DIR" ]; then
if [ -d "$ETHERPAD_DIR/.git" ]; then
warn "$ETHERPAD_DIR already exists; updating to $ETHERPAD_BRANCH."
cd "$ETHERPAD_DIR" || fatal "Cannot cd into $ETHERPAD_DIR"
# Verify the existing checkout points at the expected remote.
EXISTING_REMOTE=$(git remote get-url origin 2>/dev/null || echo "")
if [ -n "$EXISTING_REMOTE" ] && [ "$EXISTING_REMOTE" != "$ETHERPAD_REPO" ]; then
fatal "$ETHERPAD_DIR is checked out from '$EXISTING_REMOTE', expected '$ETHERPAD_REPO'. Refusing to overwrite."
fi
# Refuse to clobber meaningful local changes. pnpm-lock.yaml is excluded
# because `pnpm i` rewrites it during installation, which would otherwise
# make every re-run of the installer fail.
DIRTY=$(git status --porcelain 2>/dev/null | awk '$2 != "pnpm-lock.yaml" {print}')
if [ -n "$DIRTY" ]; then
printf '%s\n' "$DIRTY" >&2
fatal "$ETHERPAD_DIR has uncommitted changes. Commit/stash them or remove the directory."
fi
git fetch --tags --prune origin || fatal "git fetch failed in $ETHERPAD_DIR"
# Discard any pnpm-lock.yaml changes from a prior pnpm install so the
# subsequent checkout doesn't refuse to overwrite local changes.
git checkout -- pnpm-lock.yaml 2>/dev/null || true
# Switch to the requested branch / tag and fast-forward to it.
if git show-ref --verify --quiet "refs/remotes/origin/$ETHERPAD_BRANCH"; then
git checkout -B "$ETHERPAD_BRANCH" "origin/$ETHERPAD_BRANCH" || \
fatal "git checkout $ETHERPAD_BRANCH failed"
elif git show-ref --verify --quiet "refs/tags/$ETHERPAD_BRANCH"; then
git checkout --detach "refs/tags/$ETHERPAD_BRANCH" || \
fatal "git checkout tag $ETHERPAD_BRANCH failed"
else
fatal "Branch or tag '$ETHERPAD_BRANCH' not found on origin."
fi
INSTALLED_REV=$(git rev-parse --short HEAD)
step "Updated $ETHERPAD_DIR to $ETHERPAD_BRANCH @ $INSTALLED_REV"
cd - >/dev/null || exit 1
else
fatal "$ETHERPAD_DIR exists and is not a git checkout. Aborting."
fi
else
step "Cloning Etherpad ($ETHERPAD_BRANCH) into $ETHERPAD_DIR"
git clone --depth 1 --branch "$ETHERPAD_BRANCH" "$ETHERPAD_REPO" "$ETHERPAD_DIR"
fi
cd "$ETHERPAD_DIR"
# ---------- install + build ----------
step "Installing dependencies (pnpm i)"
pnpm i
step "Building Etherpad (pnpm run build:etherpad)"
pnpm run build:etherpad
# ---------- done ----------
printf '\n%s🎉 Etherpad is installed in %s%s\n' "$green" "$ETHERPAD_DIR" "$reset"
printf 'To start Etherpad:\n'
printf ' cd %s && pnpm run prod\n' "$ETHERPAD_DIR"
printf 'Then open http://localhost:9001 in your browser.\n\n'
if [ "${ETHERPAD_RUN:-0}" = "1" ]; then
step "Starting Etherpad on http://localhost:9001"
exec pnpm run prod
fi