Report update progress and log to Hammerhead while updating

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

.dockerignore

@@ -0,0 +1,3 @@
+# The image only packages the binaries that deploy/build.sh already built.
+*
+!dist/bin

.env.example

@@ -9,3 +9,7 @@ BAMBOO_TOKEN=
 
 # Folder for this agent's WireGuard key.
 #BAMBOO_DATA=./bamboo-data
+
+# Check for new releases every few hours and update and restart by itself (Linux and macOS).
+# setup.sh turns this on; remove it to update by hand.
+#BAMBOO_AUTO_UPDATE=1

.gitea/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    env:
+      GOPRIVATE: git.veillax.com
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
+      # Go fetches the other sharks modules straight from this server. This is harmless
+      # for public repositories and is what makes private ones work.
+      - name: Let Go fetch modules from this server
+        run: git config --global url."https://x-access-token:${{ secrets.GITHUB_TOKEN }}@git.veillax.com/".insteadOf "https://git.veillax.com/"
+
+      - name: Formatting
+        run: |
+          unformatted=$(gofmt -l .)
+          if [ -n "$unformatted" ]; then
+            echo "These files need gofmt:"
+            echo "$unformatted"
+            exit 1
+          fi
+
+      - name: Shell scripts parse
+        run: |
+          for f in deploy/*.sh; do sh -n "$f"; done
+
+      - name: Vet
+        run: go vet ./...
+
+      - name: Test
+        run: go test ./...
+
+      # Catches platform-specific breakage before a release is tagged.
+      - name: Every release platform compiles
+        run: |
+          for t in linux/amd64 linux/arm64 linux/arm windows/amd64 darwin/amd64 darwin/arm64; do
+            echo "building for $t"
+            GOOS=${t%/*} GOARCH=${t#*/} GOARM=7 CGO_ENABLED=0 go build -o /dev/null ./cmd/bamboo
+          done

.gitea/workflows/release.yml

@@ -0,0 +1,62 @@
+name: Release
+
+# Push a tag such as v0.2.0 to build and publish a release:
+#   git tag -a v0.2.0 -m "bamboo v0.2.0" && git push origin v0.2.0
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    env:
+      GOPRIVATE: git.veillax.com
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # release notes come from the history since the previous tag
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
+      - name: Let Go fetch modules from this server
+        run: git config --global url."https://x-access-token:${{ secrets.GITHUB_TOKEN }}@git.veillax.com/".insteadOf "https://git.veillax.com/"
+
+      - name: Test
+        run: |
+          go vet ./...
+          go test ./...
+
+      - name: Build release archives
+        run: sh deploy/build.sh "${GITHUB_REF_NAME}"
+
+      # Optional secret RELEASE_TOKEN: an access token that can write releases, for
+      # servers where the automatic job token can't.
+      - name: Publish the release
+        env:
+          TOKEN: ${{ secrets.RELEASE_TOKEN || secrets.GITHUB_TOKEN }}
+        run: sh deploy/publish-release.sh "${GITHUB_REF_NAME}"
+
+      # Skipped when the repository variable PUBLISH_DOCKER is "false", or fails alone
+      # if this runner has no Docker: the release above is already published by then.
+      # Optional secret REGISTRY_TOKEN (and variable REGISTRY_USER): an access token
+      # with package write permission, for servers where the job token can't push.
+      - name: Build and push the container image
+        if: ${{ vars.PUBLISH_DOCKER != 'false' }}
+        env:
+          REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN || secrets.GITHUB_TOKEN }}
+          REGISTRY_USER: ${{ vars.REGISTRY_USER || github.actor }}
+        run: |
+          host=${GITHUB_SERVER_URL#*://}
+          owner=$(echo "$GITHUB_REPOSITORY_OWNER" | tr 'A-Z' 'a-z')
+          image="$host/$owner/bamboo"
+          echo "$REGISTRY_TOKEN" | docker login "$host" -u "$REGISTRY_USER" --password-stdin
+          # a container-driver builder can build several architectures in one go
+          docker buildx create --name release --driver docker-container --use >/dev/null 2>&1 || docker buildx use release
+          tags="-t $image:$GITHUB_REF_NAME"
+          case "$GITHUB_REF_NAME" in
+            *-*) ;;                       # pre-releases (v1.0.0-rc1) don't move :latest
+            *) tags="$tags -t $image:latest" ;;
+          esac
+          docker buildx build --platform linux/amd64,linux/arm64 $tags --push .

.gitignore

@@ -2,3 +2,4 @@ bin/
 *-data/
 .env
 wg.key
+dist/

Dockerfile

@@ -0,0 +1,20 @@
+# syntax=docker/dockerfile:1
+# Packages the binaries deploy/build.sh already built (dist/bin/linux_<arch>/bamboo),
+# so the arm64 image needs no emulation. Build it with:  sh deploy/build.sh && docker buildx build .
+FROM --platform=$BUILDPLATFORM alpine:3.22 AS prep
+RUN apk add --no-cache ca-certificates \
+ && mkdir /data && chown 65532:65532 /data
+
+FROM scratch
+ARG TARGETARCH
+LABEL org.opencontainers.image.title="Bamboo" \
+      org.opencontainers.image.description="Site agent: connects a private network to the edge over WireGuard" \
+      org.opencontainers.image.source="https://git.veillax.com/Veillax/bamboo" \
+      org.opencontainers.image.licenses="AGPL-3.0-only"
+COPY --from=prep /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt
+COPY --from=prep --chown=65532:65532 /data /data
+COPY dist/bin/linux_${TARGETARCH}/bamboo /bamboo
+USER 65532:65532
+ENV BAMBOO_DATA=/data
+VOLUME ["/data"]
+ENTRYPOINT ["/bamboo"]

README.md

@@ -30,6 +30,44 @@ Settings and secrets can live in a `.env` file instead of the command line; see
 - **Docker discovery:** with `-docker`, lists running containers (and their ports and networks) so you can pick one as a target in the dashboard.
 - **Mail relay:** for a mail egress configured in the dashboard, opens a small SMTP relay on this machine (default `127.0.0.1:2525`). Point your mail server at it (Postfix: `relayhost = [127.0.0.1]:2525`) and each outgoing message leaves from the edge's public IP, so reverse DNS, SPF and your HELO name line up. Supports `AUTH PLAIN/LOGIN`, requires a password if it listens beyond `127.0.0.1`, relays one destination domain per transaction (extra domains get `452` so your server resends them separately), and passes your server's queue and retries through unchanged. 50 MB message limit.
 
+## Deploying
+
+Releases are built by Gitea Actions. Pushing a tag such as `v0.2.0` runs `.gitea/workflows/release.yml`, which tests the code, builds Bamboo for Linux (amd64, arm64, armv7), Windows (amd64) and macOS (amd64, arm64), publishes the archives with a `SHA256SUMS` file on the Releases page, and pushes a multi-architecture container image to this server's registry (`git.veillax.com/veillax/bamboo`). Every push and pull request runs `.gitea/workflows/ci.yml`: formatting, vet, tests, and a check that every release platform still compiles.
+
+**On a Linux server (systemd)**
+
+```
+curl -LO https://git.veillax.com/Veillax/bamboo/releases/download/v0.1.0/bamboo_v0.1.0_linux_amd64.tar.gz
+curl -LO https://git.veillax.com/Veillax/bamboo/releases/download/v0.1.0/SHA256SUMS
+sha256sum -c --ignore-missing SHA256SUMS
+tar xzf bamboo_v0.1.0_linux_amd64.tar.gz && cd bamboo_v0.1.0_linux_amd64
+sudo ./install.sh                 # installs the binary and a hardened systemd service
+sudoedit /etc/bamboo/bamboo.env   # your settings and secrets
+sudo systemctl start bamboo
+```
+
+Use `linux_arm64` or `linux_arm` for Raspberry Pi and other ARM machines. To upgrade, repeat the same steps: your settings and data are kept. `sudo ./install.sh --uninstall` removes the service and binary but leaves `/etc/bamboo` and `/var/lib/bamboo` alone. `bamboo -version` tells you which build is running.
+
+**Updates**
+
+Set `BAMBOO_AUTO_UPDATE=1` (or pass `-auto-update`) and Bamboo checks this server for a newer release every few hours, verifies it against `SHA256SUMS`, checks that the new binary runs, swaps it in and restarts itself. It only follows full releases (never pre-releases), never downgrades, and keeps the old binary if anything looks wrong. `setup.sh` turns it on. It is not available on Windows, and it is for the systemd and plain-binary installs: with Docker, pull a new image instead.
+
+**With Docker**
+
+```
+cp .env.example .env              # fill it in
+docker compose -f deploy/docker-compose.yml up -d
+```
+
+The image is `git.veillax.com/veillax/bamboo:<version>` (and `:latest` for full releases). The compose file is in the repository and inside each Linux archive.
+
+**Setting up the build (once)**
+
+- A Gitea Actions runner with the label `ubuntu-latest`, and Docker on it if you want the container image.
+- Nothing else is required: the workflows use the automatic job token. If your server doesn't let that token publish releases or packages, add the secrets `RELEASE_TOKEN` and `REGISTRY_TOKEN` (access tokens with release and package write permission) and optionally the variable `REGISTRY_USER`.
+- To skip the container image, set the repository variable `PUBLISH_DOCKER` to `false`.
+- Build locally with `sh deploy/build.sh` (archives in `dist/`).
+
 ## Build and test
 
 ```

bamboo.go

@@ -21,6 +21,7 @@ import (
 	"strconv"
 	"strings"
 	"sync"
+	"sync/atomic"
 	"time"
 
 	"git.veillax.com/Veillax/reef/docker"
@@ -34,6 +35,11 @@ type Config struct {
 	Token      string
 	DataDir    string // holds this agent's WireGuard key
 	Docker     bool   // report local Docker containers so they can be picked as targets
+
+	// Version, AutoUpdate and UpdateNow work as in blacktip.Config.
+	Version    string
+	AutoUpdate bool
+	UpdateNow  func(ctx context.Context, progress func(stage string, pct int, line string)) (newVersion string, err error)
 }
 
 type Bamboo struct {
@@ -50,6 +56,14 @@ type Bamboo struct {
 	edges   []model.EdgeRef
 	lastRep string
 
+	updating  atomic.Bool
+	updateMsg string // outcome of the update Hammerhead asked for, reported back
+	updateID  string // the request that updateMsg answers
+	updStage  string // progress of the running update, reported to Hammerhead
+	updPct    int
+	updLog    []string
+	updSent   time.Time
+
 	mail    map[string]*mailRun
 	mailErr map[string]string // mail egress ID -> "" (listening) or an error
 }
@@ -143,6 +157,9 @@ func (b *Bamboo) apply(cfg *model.SiteConfig) {
 	b.mu.Lock()
 	b.version = cfg.Version
 	b.edges = cfg.Edges
+	if cfg.UpdateID != "" {
+		b.requestUpdate(cfg.UpdateID)
+	}
 	if cfg.TunnelIP != b.tunIP && b.tun != nil {
 		b.tun.Close()
 		b.tun = nil
@@ -246,7 +263,11 @@ func (b *Bamboo) report() {
 		containers, _ = docker.List(ctx)
 		cancel()
 	}
-	body, _ := json.Marshal(model.SiteReport{PublicKey: b.wgPub, Connected: ids, Containers: containers, MailEgress: b.mailStatus()})
+	b.mu.Lock()
+	msg, uid, stage, pct, ulog := b.updateMsg, b.updateID, b.updStage, b.updPct, append([]string(nil), b.updLog...)
+	b.mu.Unlock()
+	body, _ := json.Marshal(model.SiteReport{PublicKey: b.wgPub, Connected: ids, Containers: containers, MailEgress: b.mailStatus(),
+		Version: b.cfg.Version, AutoUpdate: b.cfg.AutoUpdate, UpdateMsg: msg, UpdateID: uid, UpdateStage: stage, UpdatePct: pct, UpdateLog: ulog})
 	req, _ := http.NewRequest("POST", b.cfg.Hammerhead+"/site/report", bytes.NewReader(body))
 	req.Header.Set("Authorization", "Bearer "+b.cfg.Token)
 	req.Header.Set("Content-Type", "application/json")
@@ -414,3 +435,73 @@ func serveUDP(pc net.PacketConn) {
 		}
 	}
 }
+
+// requestUpdate acts on "update now" from Hammerhead (id identifies the request). It only ever installs
+// what this machine's own auto-update would (the newest release from its configured server), and only
+// when auto-update is on. Caller holds b.mu.
+func (b *Bamboo) requestUpdate(id string) {
+	if id == b.updateID {
+		return // already handled, or in progress
+	}
+	b.updateID, b.updateMsg = id, ""
+	b.updStage, b.updPct, b.updLog = "starting", 0, nil
+	b.updNote("Update requested from the dashboard")
+	if !b.cfg.AutoUpdate || b.cfg.UpdateNow == nil {
+		b.updateMsg = "auto-update is off on this machine (set BAMBOO_AUTO_UPDATE=1 and restart it)"
+		b.updStage = "failed"
+		b.updNote("Refused: " + b.updateMsg)
+		go b.report()
+		return
+	}
+	if !b.updating.CompareAndSwap(false, true) {
+		b.updateMsg = "another update is already running"
+		b.updStage = "failed"
+		b.updNote("Refused: " + b.updateMsg)
+		go b.report()
+		return
+	}
+	go func() {
+		defer b.updating.Store(false)
+		tag, err := b.cfg.UpdateNow(b.ctx, b.updProgress) // on success this restarts the process and does not return
+		b.mu.Lock()
+		switch {
+		case err != nil:
+			b.updateMsg = "update failed: " + err.Error()
+		case tag == "":
+			b.updateMsg = "already on the newest release"
+		default:
+			b.updateMsg = "updated to " + tag + ", restarting"
+		}
+		b.mu.Unlock()
+		b.report()
+	}()
+}
+
+// updNote adds a timestamped line to the update log. Caller holds b.mu.
+func (b *Bamboo) updNote(line string) {
+	b.updLog = append(b.updLog, time.Now().Format("15:04:05")+" "+line)
+	if len(b.updLog) > 200 {
+		b.updLog = b.updLog[len(b.updLog)-200:]
+	}
+}
+
+// updProgress is called by the updater as it works; Hammerhead gets a fresh report at most once a
+// second (and straight away for every new log line), so its progress bar follows along.
+func (b *Bamboo) updProgress(stage string, pct int, line string) {
+	b.mu.Lock()
+	b.updStage = stage
+	if pct >= 0 {
+		b.updPct = pct
+	}
+	if line != "" {
+		b.updNote(line)
+	}
+	send := line != "" || time.Since(b.updSent) > time.Second
+	if send {
+		b.updSent = time.Now()
+	}
+	b.mu.Unlock()
+	if send {
+		go b.report()
+	}
+}

cmd/bamboo/main.go

@@ -11,8 +11,12 @@ import (
 
 	"git.veillax.com/Veillax/bamboo"
 	"git.veillax.com/Veillax/reef/dotenv"
+	"git.veillax.com/Veillax/reef/selfupdate"
 )
 
+// version is set at build time (deploy/build.sh).
+var version = "dev"
+
 func env(k, def string) string {
 	if v := os.Getenv(k); v != "" {
 		return v
@@ -31,14 +35,31 @@ func main() {
 	data := flag.String("data", env("BAMBOO_DATA", "./bamboo-data"), "directory for this agent's WireGuard key")
 	dockerOn := flag.Bool("docker", os.Getenv("BAMBOO_DOCKER") == "1", "report local Docker containers so they can be picked as targets in the UI")
 	flag.String("env", ".env", "file to read secrets and settings from")
+	autoUpdate := flag.Bool("auto-update", os.Getenv("BAMBOO_AUTO_UPDATE") == "1", "check for new releases every few hours and update and restart by itself (Linux and macOS)")
+	showVersion := flag.Bool("version", false, "print the version and exit")
 	flag.Parse()
+	if *showVersion {
+		os.Stdout.WriteString("bamboo " + version + "\n")
+		return
+	}
 	if *hh == "" || *token == "" {
 		flag.Usage()
 		os.Exit(2)
 	}
+	log.Printf("bamboo %s starting", version)
 	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
 	defer stop()
-	b, err := bamboo.New(bamboo.Config{Hammerhead: strings.TrimRight(*hh, "/"), Token: *token, DataDir: *data, Docker: *dockerOn})
+	upd := selfupdate.Config{Server: "https://git.veillax.com", Repo: "Veillax/bamboo", App: "bamboo", Current: version, Logf: log.Printf}
+	if *autoUpdate {
+		go selfupdate.Run(ctx, upd)
+	}
+	b, err := bamboo.New(bamboo.Config{Hammerhead: strings.TrimRight(*hh, "/"), Token: *token, DataDir: *data, Docker: *dockerOn,
+		Version: version, AutoUpdate: *autoUpdate,
+		UpdateNow: func(ctx context.Context, progress func(string, int, string)) (string, error) {
+			c := upd
+			c.Progress = func(e selfupdate.Event) { progress(e.Stage, e.Pct, e.Line) }
+			return selfupdate.CheckOnce(ctx, c)
+		}})
 	if err != nil {
 		log.Fatal(err)
 	}

deploy/bamboo.service

@@ -0,0 +1,29 @@
+[Unit]
+Description=Bamboo: site agent that connects a private network to the edge
+Documentation=https://git.veillax.com/Veillax/bamboo
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+User=bamboo
+Group=bamboo
+EnvironmentFile=-/etc/bamboo/bamboo.env
+ExecStart=/usr/local/lib/bamboo/bamboo -data /var/lib/bamboo
+WorkingDirectory=/var/lib/bamboo
+Restart=on-failure
+RestartSec=3
+
+# It makes outbound connections only, so it needs no privileges at all.
+NoNewPrivileges=true
+ProtectSystem=strict
+ReadWritePaths=/var/lib/bamboo /usr/local/lib/bamboo
+ProtectHome=true
+PrivateTmp=true
+ProtectKernelTunables=true
+ProtectControlGroups=true
+
+# To list this machine's Docker containers (BAMBOO_DOCKER=1), let the service read
+# the Docker socket:   sudo usermod -aG docker bamboo   then restart it.
+
+[Install]
+WantedBy=multi-user.target

deploy/build.sh

@@ -0,0 +1,50 @@
+#!/bin/sh
+# Builds bamboo for every release platform and packs the archives into dist/.
+#
+#   deploy/build.sh [version]      version defaults to `git describe`
+#
+# Output:
+#   dist/bin/<os>_<arch>/bamboo             the raw binaries (the Docker image uses the linux ones)
+#   dist/bamboo_<version>_<os>_<arch>.tar.gz or .zip
+#   dist/SHA256SUMS
+#
+# Set TARGETS="linux/amd64 linux/arm64" to build fewer platforms.
+set -eu
+NAME=bamboo
+cd "$(dirname "$0")/.."
+VERSION=${1:-$(git describe --tags --always 2>/dev/null || echo dev)}
+TARGETS=${TARGETS:-"linux/amd64 linux/arm64 linux/arm windows/amd64 darwin/amd64 darwin/arm64"}
+
+rm -rf dist
+mkdir -p dist/bin dist/stage
+for t in $TARGETS; do
+	os=${t%/*}
+	arch=${t#*/}
+	ext=""
+	[ "$os" = windows ] && ext=".exe"
+	out="dist/bin/${os}_${arch}"
+	mkdir -p "$out"
+	echo "building $NAME $VERSION for $os/$arch"
+	CGO_ENABLED=0 GOOS=$os GOARCH=$arch GOARM=7 \
+		go build -trimpath -ldflags "-s -w -X main.version=$VERSION" -o "$out/$NAME$ext" "./cmd/$NAME"
+
+	pkg="${NAME}_${VERSION}_${os}_${arch}"
+	stage="dist/stage/$pkg"
+	mkdir -p "$stage"
+	cp "$out/$NAME$ext" "$stage/"
+	for f in LICENSE README.md .env.example; do
+		[ -f "$f" ] && cp "$f" "$stage/"
+	done
+	if [ "$os" = linux ]; then
+		cp deploy/install.sh "deploy/$NAME.service" deploy/docker-compose.yml "$stage/"
+		chmod +x "$stage/install.sh"
+	fi
+	if [ "$os" = windows ] && command -v zip >/dev/null 2>&1; then
+		(cd dist/stage && zip -qr "../$pkg.zip" "$pkg")
+	else
+		tar -C dist/stage -czf "dist/$pkg.tar.gz" "$pkg"
+	fi
+done
+rm -rf dist/stage
+(cd dist && sha256sum $(ls | grep -E '\.(tar\.gz|zip)$') > SHA256SUMS)
+echo "done: $(ls dist | grep -cE '\.(tar\.gz|zip)$') archives in dist/"

deploy/docker-compose.yml

@@ -0,0 +1,23 @@
+# Run Bamboo with Docker inside your home or private network:
+#   cp .env.example .env     (then set BAMBOO_HAMMERHEAD and BAMBOO_TOKEN)
+#   docker compose up -d
+#
+# Bamboo only makes outbound connections, so nothing needs opening. Host networking
+# lets it reach services on this machine (127.0.0.1) as well as the rest of your LAN;
+# switch it off if your targets are all on other machines.
+services:
+  bamboo:
+    image: git.veillax.com/veillax/bamboo:latest
+    restart: unless-stopped
+    network_mode: host
+    env_file: .env
+    volumes:
+      - bamboo-data:/data
+      # To list this machine's Docker containers as targets (BAMBOO_DOCKER=1), share the
+      # socket and let the container's user read it (find the group id: getent group docker):
+      # - /var/run/docker.sock:/var/run/docker.sock:ro
+    # group_add:
+    #   - "999"
+
+volumes:
+  bamboo-data:

deploy/install.sh

@@ -0,0 +1,79 @@
+#!/bin/sh
+# Installs bamboo as a systemd service from the files in this folder.
+#
+#   sudo ./install.sh              install or upgrade (your settings and data are kept)
+#   sudo ./install.sh --start      the same, then start (or restart) the service
+#   sudo ./install.sh --uninstall  remove the service and binary (keeps the settings and data)
+#
+# Files: /usr/local/lib/bamboo/bamboo (linked from /usr/local/bin/bamboo), /etc/systemd/system/bamboo.service,
+#        /etc/bamboo/bamboo.env (your settings and secrets), /var/lib/bamboo (data).
+# Set DESTDIR=/some/dir to stage everything there without touching the system.
+set -eu
+NAME=bamboo
+HERE=$(cd "$(dirname "$0")" && pwd)
+ROOT=${DESTDIR:-}
+BIN=$ROOT/usr/local/bin/$NAME
+UNIT=$ROOT/etc/systemd/system/$NAME.service
+CONF=$ROOT/etc/$NAME
+ENVFILE=$CONF/$NAME.env
+DATA=$ROOT/var/lib/$NAME
+LIB=$ROOT/usr/local/lib/$NAME # the program lives here, owned by the service, so auto-update can replace it
+
+say() { printf '%s\n' "$*"; }
+real() { [ -z "${DESTDIR:-}" ]; } # are we touching the real system?
+
+if real; then
+	[ "$(id -u)" = 0 ] || { say "Run this as root:  sudo $0 $*"; exit 1; }
+	command -v systemctl > /dev/null 2>&1 || { say "systemd wasn't found. Run $NAME directly (see the README) or use Docker."; exit 1; }
+fi
+
+if [ "${1:-}" = "--uninstall" ]; then
+	if real; then
+		systemctl disable --now "$NAME" > /dev/null 2>&1 || true
+	fi
+	rm -f "$UNIT" "$BIN" "$LIB/$NAME"
+	if real; then
+		systemctl daemon-reload || true
+	fi
+	say "Removed $NAME. Left in place: $CONF and $DATA (delete them yourself if you want them gone)."
+	exit 0
+fi
+
+[ -f "$HERE/$NAME" ] || { say "Can't find the $NAME binary next to this script."; exit 1; }
+
+if real && ! id "$NAME" > /dev/null 2>&1; then
+	useradd --system --home-dir "/var/lib/$NAME" --shell /usr/sbin/nologin "$NAME"
+	say "Created the system user '$NAME'."
+fi
+
+mkdir -p "$ROOT/usr/local/bin" "$ROOT/etc/systemd/system" "$CONF" "$DATA"
+mkdir -p "$LIB"
+install -m 0755 "$HERE/$NAME" "$LIB/$NAME.new"
+mv -f "$LIB/$NAME.new" "$LIB/$NAME" # atomic, so upgrading a running service is safe
+rm -f "$BIN"
+LINK=/usr/local/lib/$NAME/$NAME
+[ -z "${DESTDIR:-}" ] || LINK=$LIB/$NAME # staging: point inside the staging folder
+ln -s "$LINK" "$BIN"
+install -m 0644 "$HERE/$NAME.service" "$UNIT"
+if [ ! -f "$ENVFILE" ]; then
+	install -m 0600 "$HERE/.env.example" "$ENVFILE"
+	say "Created $ENVFILE. Edit it before starting."
+fi
+if real; then
+	chown -R "$NAME:$NAME" "$DATA" "$LIB"
+fi
+
+if real; then
+	systemctl daemon-reload
+	systemctl enable "$NAME" > /dev/null 2>&1
+	if [ "${1:-}" = "--start" ] || systemctl is-active --quiet "$NAME"; then
+		systemctl restart "$NAME"
+		say "$NAME is running."
+	fi
+fi
+
+say "Installed $("$LIB/$NAME" -version 2> /dev/null || echo "$NAME")."
+say "Next:"
+say "  1. edit $ENVFILE"
+say "  2. systemctl start $NAME      (or run this again with --start)"
+say "  3. journalctl -u $NAME -f     to watch it"

deploy/publish-release.sh

@@ -0,0 +1,71 @@
+#!/bin/sh
+# Creates (or updates) the Gitea release for a tag and uploads what deploy/build.sh made.
+#
+#   TOKEN=<access token that can write releases> deploy/publish-release.sh v0.2.0
+#
+# In Gitea Actions GITHUB_SERVER_URL and GITHUB_REPOSITORY are already set. Safe to
+# re-run: an existing release is reused and assets with the same name are replaced.
+set -eu
+TAG=${1:?usage: publish-release.sh <tag>}
+: "${TOKEN:?set TOKEN to a Gitea access token that can write releases}"
+SERVER=${GITHUB_SERVER_URL:-${GITEA_SERVER_URL:-https://git.veillax.com}}
+REPO=${GITHUB_REPOSITORY:-Veillax/bamboo}
+API="$SERVER/api/v1/repos/$REPO"
+AUTH="Authorization: token $TOKEN"
+
+# a JSON helper without needing jq: any python will do
+PY=python3
+python3 -c 'pass' > /dev/null 2>&1 || PY=python
+json() { "$PY" -c "$1"; }
+
+# release notes: the commit subjects since the previous tag
+prev=$(git describe --tags --abbrev=0 "$TAG^" 2>/dev/null || true)
+if [ -n "$prev" ]; then
+	notes=$(git log --pretty='format:- %s' "$prev..$TAG")
+else
+	notes=$(git log --pretty='format:- %s' "$TAG")
+fi
+prerelease=false
+case "$TAG" in *-*) prerelease=true ;; esac
+
+body=$(NOTES="$notes" TAG="$TAG" PRE="$prerelease" json '
+import json, os
+print(json.dumps({"tag_name": os.environ["TAG"], "name": os.environ["TAG"], "body": os.environ["NOTES"],
+                  "draft": False, "prerelease": os.environ["PRE"] == "true"}))')
+
+# reuse the release when a failed job is re-run
+id=$(curl -fsS -H "$AUTH" "$API/releases/tags/$TAG" 2>/dev/null | json 'import sys, json; print(json.load(sys.stdin)["id"])' 2>/dev/null || true)
+if [ -z "$id" ]; then
+	echo "creating release $TAG"
+	id=$(curl -fsS -X POST -H "$AUTH" -H 'Content-Type: application/json' -d "$body" "$API/releases" | json 'import sys, json; print(json.load(sys.stdin)["id"])')
+else
+	echo "release $TAG already exists (id $id): replacing its files"
+fi
+
+# the ids of the release's assets with a given name (a failed upload can leave a partial one behind)
+asset_ids() {
+	curl -fsS -H "$AUTH" "$API/releases/$id/assets" | "$PY" -c 'import sys, json
+for a in json.load(sys.stdin):
+    if a["name"] == sys.argv[1]:
+        print(a["id"])' "$1"
+}
+
+for f in dist/*.tar.gz dist/*.zip dist/SHA256SUMS; do
+	[ -f "$f" ] || continue
+	name=$(basename "$f")
+	n=1
+	while :; do
+		for aid in $(asset_ids "$name"); do
+			curl -fsS -X DELETE -H "$AUTH" "$API/releases/$id/assets/$aid" > /dev/null
+		done
+		echo "uploading $name (attempt $n)"
+		if curl -fsS --max-time 1200 -X POST -H "$AUTH" -F "attachment=@$f" "$API/releases/$id/assets?name=$name" > /dev/null; then
+			break
+		fi
+		# large uploads can hit a proxy timeout (HTTP 502); try again
+		[ "$n" -lt 5 ] || { echo "giving up on $name after $n attempts" >&2; exit 1; }
+		n=$((n + 1))
+		sleep $((n * 10))
+	done
+done
+echo "published $SERVER/$REPO/releases/tag/$TAG"

go.mod

@@ -2,7 +2,7 @@ module git.veillax.com/Veillax/bamboo
 
 go 1.27.3
 
-require git.veillax.com/Veillax/reef v0.1.0
+require git.veillax.com/Veillax/reef v0.1.7
 
 require (
 	github.com/Microsoft/go-winio v0.6.4 // indirect

go.sum

@@ -1,5 +1,13 @@
 git.veillax.com/Veillax/reef v0.1.0 h1:O0OhEKFx2CsvACJ20sfzJNjGsngomtfDdKdxu4ROpCs=
 git.veillax.com/Veillax/reef v0.1.0/go.mod h1:ZBUd/BARO5kkpUNTP81TTY1aQXLHFR6bKDhCxckjHso=
+git.veillax.com/Veillax/reef v0.1.3 h1:RxSq2xwaup1+MieAkhlvOTZnYwPf19thFHEAe/7VxsI=
+git.veillax.com/Veillax/reef v0.1.3/go.mod h1:ZBUd/BARO5kkpUNTP81TTY1aQXLHFR6bKDhCxckjHso=
+git.veillax.com/Veillax/reef v0.1.5 h1:BydjLJsfGgU4zEIqUsePJRjPi9NgbFdmvq0M8dvJCgM=
+git.veillax.com/Veillax/reef v0.1.5/go.mod h1:ZBUd/BARO5kkpUNTP81TTY1aQXLHFR6bKDhCxckjHso=
+git.veillax.com/Veillax/reef v0.1.6 h1:NgZ4u2Z3hJ+BYD/zX9lov8fox4s2i8txtYNOpIsikVo=
+git.veillax.com/Veillax/reef v0.1.6/go.mod h1:ZBUd/BARO5kkpUNTP81TTY1aQXLHFR6bKDhCxckjHso=
+git.veillax.com/Veillax/reef v0.1.7 h1:5C2udonlJac2xvDOE5e+zDxej+AbZ9ttrNSE4owmwuU=
+git.veillax.com/Veillax/reef v0.1.7/go.mod h1:ZBUd/BARO5kkpUNTP81TTY1aQXLHFR6bKDhCxckjHso=
 github.com/Microsoft/go-winio v0.6.4 h1:kJF2pamtYCWXf0xAT8sAkwKC0pMl2HYBrRPHAqyUc+g=
 github.com/Microsoft/go-winio v0.6.4/go.mod h1:1xl5JXG4ze/m74GH6Dc4Mwxfc3VL5siRVQjIAlHH07U=
 github.com/google/btree v1.1.2 h1:xf4v41cLI2Z6FxbKm+8Bu+m8ifhj15JuZ9sa0jZCMUU=