diff --git a/.github/workflows/installer-test.yml b/.github/workflows/installer-test.yml new file mode 100644 index 00000000000..d77c277a18e --- /dev/null +++ b/.github/workflows/installer-test.yml @@ -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 diff --git a/README.md b/README.md index 492ad015d3c..5c0c8c48b1a 100644 --- a/README.md +++ b/README.md @@ -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 . + +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 diff --git a/bin/installer.ps1 b/bin/installer.ps1 new file mode 100644 index 00000000000..f1295b72fd2 --- /dev/null +++ b/bin/installer.ps1 @@ -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 +} diff --git a/bin/installer.sh b/bin/installer.sh new file mode 100755 index 00000000000..151aafd50cd --- /dev/null +++ b/bin/installer.sh @@ -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