Add self-update, including in Docker

Sandbar can install new releases itself using Reef's selfupdate, automatically with
SANDBAR_AUTO_UPDATE=1 or from a button on the Account page. In a container the new binary is
written to <data>/bin and takes over from the image at start, until the image catches up.
Tags now publish a Gitea release with archives and SHA256SUMS as well as the image.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
VeillaxandClaude Sonnet 5.5 committed 2026-10-27 04:22:54 -06:00
1 parent 955e01333d
commit 73f45fb3ae
14 files changed
+610 -20

No files matched your search

+25 -3
View File
@@ -47,6 +47,7 @@ services:
env_file: .env
environment:
SANDBAR_URL: https://sandbar.example.com
SANDBAR_AUTO_UPDATE: "1" # optional, see Updating below
volumes:
- sandbar-data:/data
@@ -62,12 +63,12 @@ docker compose up -d
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.
- Update by hand with `docker compose pull && docker compose up -d`, or let Sandbar do it (see Updating below).
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
Download an archive from the release page (Linux amd64 and arm64, Windows amd64) or build it (`go build -o bin/ ./cmd/sandbar`), copy it to the server with a `.env` file, and run it
under a service manager. A minimal systemd unit:
```ini
@@ -87,6 +88,27 @@ 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.
### Updating
Pushing a version tag publishes a release with archives and `SHA256SUMS` as well as the image. Sandbar can install
new releases itself, in Docker and as a plain binary, on Linux and macOS.
- **Automatic:** set `SANDBAR_AUTO_UPDATE=1` (or pass `-auto-update`). Sandbar checks a few minutes after start and
then every few hours, downloads the archive for its platform, checks it against `SHA256SUMS`, checks that the new
binary runs, replaces itself and restarts. Pre-releases (`v1.0.0-rc1`) are never installed.
- **On demand:** an administrator can see the newest release and click **Update** on the Account page, with or
without automatic updates on.
- **In Docker:** the image is read-only to Sandbar, and a change inside the container would be lost when it is
recreated. So the new binary is written to `<data>/bin/sandbar` on the data volume. At every start Sandbar runs
that file when it is a newer release than the image, and deletes it once the image has caught up. The container
keeps running through the update (it re-executes in place, so the process id does not change), and
`docker compose pull` still works: a newer image takes over from the volume copy.
- **Pin a version:** leave automatic updates off and use an image tag such as `:v0.2.0` instead of `:latest`.
- **Requirements:** the release page must be readable without signing in, so the repository has to be public. A
development build (`dev`) and Windows never update themselves. `SANDBAR_UPDATE_SERVER` and `SANDBAR_UPDATE_REPO`
point it at a different Gitea server or fork. If a bad update leaves Sandbar unable to start, delete
`<data>/bin/sandbar` (or set `SANDBAR_NO_OVERLAY=1`) and it starts from the image again.
### 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