Production-ready proxy: working Postgres scaling, race fixes, ops, tests, non-Docker docs (#54, #52)

.github/workflows/release.yml

@@ -0,0 +1,23 @@
+name: Release
+on:
+  push:
+    tags:
+      - 'v*'
+permissions:
+  contents: write
+jobs:
+  goreleaser:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.25'
+      - uses: goreleaser/goreleaser-action@v6
+        with:
+          version: '~> v2'
+          args: release --clean
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/test.yml

@@ -0,0 +1,33 @@
+name: Test
+on:
+  push:
+    branches: [main]
+  pull_request:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: proxy
+          POSTGRES_PASSWORD: proxy
+          POSTGRES_DB: etherpad_proxy
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U proxy"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.25'
+      - name: Vet
+        run: go vet ./...
+      - name: Test (race)
+        env:
+          PG_TEST_DSN: postgres://proxy:proxy@localhost:5432/etherpad_proxy?sslmode=disable
+        run: go test -race ./...

.goreleaser.yaml

@@ -0,0 +1,32 @@
+version: 2
+project_name: etherpad-proxy
+builds:
+  - id: etherpad-proxy
+    main: .
+    binary: etherpad-proxy
+    env:
+      - CGO_ENABLED=0
+    goos:
+      - linux
+      - darwin
+      - windows
+    goarch:
+      - amd64
+      - arm64
+archives:
+  - id: default
+    formats: [tar.gz]
+    format_overrides:
+      - goos: windows
+        formats: [zip]
+    files:
+      - README.md
+      - LICENSE.md
+      - settings.json.template
+      - support/etherpad-proxy.service
+checksum:
+  name_template: 'checksums.txt'
+release:
+  github:
+    owner: ether
+    name: etherpad-proxy

README.md

@@ -24,6 +24,94 @@ This is now a production grade reverse proxy written in Golang.
 
 Visit http://localhost:9000
 
+## Installation without Docker
+
+The proxy is a single static Go binary. You can run it directly on a host
+without Docker.
+
+### Option A: download a prebuilt binary
+
+1. Go to the [Releases page](https://github.com/ether/etherpad-proxy/releases)
+   and download the archive for your OS/architecture.
+2. Extract it: `tar xzf etherpad-proxy_*.tar.gz` (or unzip on Windows).
+3. Continue with **Configure** below.
+
+### Option B: build from source
+
+Requires Go 1.25 or newer.
+
+```bash
+git clone https://github.com/ether/etherpad-proxy.git
+cd etherpad-proxy
+go build -o etherpad-proxy .
+```
+
+### Configure
+
+1. Copy the template and edit it:
+   ```bash
+   cp settings.json.template settings.json
+   ```
+2. Set `port` (proxy listen port), optionally `managementPort`
+   (default `8081`, serves `/pads`, `/metrics`, `/healthz`, `/readyz`), your
+   `backends`, and a database (see **Database** below).
+3. The settings path defaults to `./settings.json`; override it with the
+   `SETTINGS_FILE` environment variable.
+
+### Run
+
+```bash
+SETTINGS_FILE=/path/to/settings.json ./etherpad-proxy
+```
+
+The proxy listens on `port`; management/metrics/health endpoints listen on
+`managementPort`.
+
+### Database
+
+- **SQLite (default, single instance):** set `dbSettings.filename`, e.g.
+  `"db/etherpad-proxy.db"`. No external services required. Create the directory
+  first: `mkdir -p db`.
+- **Postgres (recommended for multiple proxy instances):** set
+  `dbSettings.postgresConnstr`. With a shared Postgres, several proxy instances
+  share routing state and assign new pads atomically, so they never route the
+  same pad to different backends.
+
+  Provision a database and user, for example:
+  ```sql
+  CREATE USER proxy WITH PASSWORD 'changeme';
+  CREATE DATABASE etherpad_proxy OWNER proxy;
+  ```
+  Then set:
+  ```json
+  "dbSettings": {
+    "postgresConnstr": "postgres://proxy:changeme@db-host:5432/etherpad_proxy?sslmode=disable"
+  }
+  ```
+  The proxy creates its tables automatically on first start. Set exactly one of
+  `filename` or `postgresConnstr`.
+
+### Run as a systemd service (Linux)
+
+A sample unit is provided at `support/etherpad-proxy.service`.
+
+```bash
+sudo useradd --system --no-create-home --shell /usr/sbin/nologin etherpad-proxy
+sudo mkdir -p /opt/etherpad-proxy/db
+sudo cp etherpad-proxy /opt/etherpad-proxy/
+sudo cp settings.json /opt/etherpad-proxy/
+sudo cp support/etherpad-proxy.service /etc/systemd/system/
+sudo chown -R etherpad-proxy:etherpad-proxy /opt/etherpad-proxy
+sudo systemctl daemon-reload
+sudo systemctl enable --now etherpad-proxy
+```
+
+Check status and logs:
+```bash
+systemctl status etherpad-proxy
+journalctl -u etherpad-proxy -f
+```
+
 ## Settings
 
 Settings come from ``settings.json``, see ``settings.json.template`` for an example to modify for your environment.

checkAvailability_test.go

@@ -0,0 +1,59 @@
+package main
+
+import (
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"slices"
+	"strconv"
+	"testing"
+
+	"github.com/ether/etherpad-proxy/models"
+)
+
+// newStatsBackend starts a test server replying to /stats with the given
+// activePads count, and returns its host and port.
+func newStatsBackend(t *testing.T, activePads int) (string, int) {
+	t.Helper()
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path == "/stats" {
+			fmt.Fprintf(w, `{"activePads": %d}`, activePads)
+			return
+		}
+		w.WriteHeader(http.StatusNotFound)
+	}))
+	t.Cleanup(srv.Close)
+	u, _ := url.Parse(srv.URL)
+	port, _ := strconv.Atoi(u.Port())
+	return u.Hostname(), port
+}
+
+func TestCheckAvailabilityCapacityAndDown(t *testing.T) {
+	okHost, okPort := newStatsBackend(t, 1)       // under capacity -> up + available
+	fullHost, fullPort := newStatsBackend(t, 99)  // over capacity -> up but not available
+
+	settings := models.Settings{
+		MaxPadsPerInstance: 5,
+		Backends: map[string]models.Backend{
+			"ok":   {Host: okHost, Port: okPort},
+			"full": {Host: fullHost, Port: fullPort},
+			"down": {Host: "127.0.0.1", Port: 1}, // nothing listening -> not up
+		},
+	}
+
+	got := checkAvailability(settings)
+
+	if !slices.Contains(got.Up, "ok") || !slices.Contains(got.Up, "full") {
+		t.Fatalf("expected ok and full to be up, got %v", got.Up)
+	}
+	if slices.Contains(got.Up, "down") {
+		t.Fatalf("down backend should not be up, got %v", got.Up)
+	}
+	if !slices.Contains(got.Available, "ok") {
+		t.Fatalf("ok should be available, got %v", got.Available)
+	}
+	if slices.Contains(got.Available, "full") {
+		t.Fatalf("full backend should not be available, got %v", got.Available)
+	}
+}

databases/interfaces/iDB.go

@@ -10,4 +10,8 @@ type IDB interface {
 	Set(id string, backend models.DBBackend) error
 	GetAllPads() (map[string]string, error)
 	GetClashByPadID(id string) ([]string, error)
+	// Assign stores candidate as the backend for padId only if no backend is
+	// already stored, and returns the backend now authoritative for padId (the
+	// pre-existing one if there was a race, otherwise candidate).
+	Assign(padId string, candidate string) (string, error)
 }