more stuff

README.md

@@ -29,7 +29,84 @@ bin/sandbar -listen :8090 -url https://sandbar.example.com
 Open `http://localhost:8090` and create the first administrator. Or set `SANDBAR_ADMIN_EMAIL` and
 `SANDBAR_ADMIN_PASSWORD` in `.env` to create it at startup.
 
-Docker: `docker run -p 8090:8090 -v sandbar-data:/data -e SANDBAR_MASTER_KEY=... sandbar`.
+## Deploying
+
+### Docker
+
+Pushing a version tag publishes a multi-architecture (amd64 and arm64) image to the registry on the same server as
+the repository, as `git.veillax.com/veillax/sandbar:<version>` and `:latest`. Generate a master key once with
+`docker run --rm git.veillax.com/veillax/sandbar -genkey`, then keep it in a `.env` file next to this compose file:
+
+```yaml
+services:
+  sandbar:
+    image: git.veillax.com/veillax/sandbar:latest
+    restart: unless-stopped
+    ports:
+      - "127.0.0.1:8090:8090"
+    env_file: .env
+    environment:
+      SANDBAR_URL: https://sandbar.example.com
+    volumes:
+      - sandbar-data:/data
+
+volumes:
+  sandbar-data:
+```
+
+```
+docker compose up -d
+```
+
+- The container runs as user 65532 and keeps its database in `/data`. Use a named volume as above. If you bind-mount
+  a folder instead, make it writable by 65532 (`chown 65532:65532 ./data`).
+- Set `SANDBAR_MASTER_KEY` yourself. Without it a key is generated inside `/data`, next to the database it protects.
+- To build the image locally, see the comment at the top of `Dockerfile`.
+- Update with `docker compose pull && docker compose up -d`. Your data stays in the volume. Copy the data folder
+  before upgrading, since there is no migration tooling yet.
+
+### Binary
+
+Build `sandbar` (`go build -o bin/ ./cmd/sandbar`; releases only publish the container image), copy it to the server with a `.env` file, and run it
+under a service manager. A minimal systemd unit:
+
+```ini
+[Unit]
+Description=Sandbar
+After=network-online.target
+
+[Service]
+User=sandbar
+WorkingDirectory=/var/lib/sandbar
+ExecStart=/usr/local/bin/sandbar -listen 127.0.0.1:8090 -env /etc/sandbar/.env
+Restart=on-failure
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Put `SANDBAR_DATA=/var/lib/sandbar` in the env file and make `/etc/sandbar/.env` readable only by the `sandbar` user.
+
+### HTTPS and a reverse proxy
+
+Sandbar serves plain HTTP, so put a reverse proxy in front of it and set `SANDBAR_URL` to the public address, since
+links in notifications use it. Caddy needs one line:
+
+```
+sandbar.example.com {
+    reverse_proxy 127.0.0.1:8090
+}
+```
+
+With nginx, turn off response buffering for the live topic feeds (`/<topic>/sse` and `/<topic>/json`), or
+subscribers see messages late: `proxy_buffering off; proxy_read_timeout 1h;`.
+
+### After the first start
+
+1. Open the address and create the administrator, or set `SANDBAR_ADMIN_EMAIL` and `SANDBAR_ADMIN_PASSWORD` first.
+2. Add an email or webhook channel and use its test button, so you know alerts will reach you.
+3. Create an API key on the Account page for scripts and monitoring agents.
+4. Set up backups (see Database below), including the master key, which must be stored apart from the data.
 
 ## How the pieces fit