restic-manager/docs/superpowers/plans/2026-05-05-p5-03-docker-only-release.md

P5-03 implementation plan — Docker-only release

Spec: docs/superpowers/specs/2026-05-05-p5-03-docker-only-release.md.

Branch: p5-03-docker-release. Do not auto-open a PR (see CLAUDE.md memory: CI runs are expensive on the self-hosted cluster).

---

Slice 1 — Server config + handler fallback

Goal: server can serve agent binaries / install scripts from a read-only "bundled assets" path when <DataDir> doesn't have them.

1. internal/server/config/config.go (or wherever Cfg lives) gains a BundledAssetsDir string field, defaulting to /opt/restic-manager/dist. Wire from RM_BUNDLED_ASSETS_DIR env var, mirroring the existing env-var conventions.
2. internal/server/http/agent_assets.go:
   • handleAgentBinary: try <DataDir>/agent-binaries/<name> first; on os.Stat ENOENT, try <BundledAssetsDir>/agent-binaries/<name>; on second ENOENT, existing 404.
   • handleInstallAsset: same dual-path, with install/ subpath.
3. Tests in internal/server/http/agent_assets_test.go (new file):
   • DataDir hit serves DataDir bytes.
   • DataDir miss + bundled hit serves bundled bytes.
   • DataDir hit shadows bundled.
   • Both miss → 404 + existing error envelope.
   • Path-traversal still rejected for install/* (regression check).

Verify: go vet ./... + go test ./internal/server/http/....

---

Slice 2 — Version ldflags on both binaries

1. cmd/server/main.go: keep var version, add var commit = "none" and var date = "unknown". Surface via existing version-log line.
2. cmd/agent/main.go: same three vars. Agent already reports agent_version in the WS hello — extend to include commit if it's already plumbed through internal/api; otherwise leave the commit out of the wire and just log it on startup.
3. Makefile: extend the make build -ldflags to set all three from git describe --tags --always + git rev-parse HEAD + UTC timestamp. Source-build users get real values, not "dev".
4. deploy/Dockerfile.server: add ARG COMMIT=none and ARG DATE=unknown; pass through -ldflags.

Verify: make build && ./bin/restic-manager-server -version (or whatever the existing flag is) prints non-dev values.

---

Slice 3 — Dockerfile bakes agents + install assets

1. Build stage cross-compiles three agents:

   RUN go build -trimpath -ldflags="-s -w \
         -X main.version=${VERSION} -X main.commit=${COMMIT} -X main.date=${DATE}" \
       -o /out/agent/restic-manager-agent-linux-amd64 ./cmd/agent
   ENV GOARCH=arm64
   RUN go build ... -o /out/agent/restic-manager-agent-linux-arm64 ./cmd/agent
   ENV GOOS=windows GOARCH=amd64
   RUN go build ... -o /out/agent/restic-manager-agent-windows-amd64.exe ./cmd/agent
   

   (Reset GOOS/GOARCH between layers via ENV. Server build stays at GOOS=linux GOARCH=$TARGETARCH.)

2. Final stage COPY --from=build:

   • /out/restic-manager-server → /usr/local/bin/
   • /out/agent/* → /opt/restic-manager/dist/agent-binaries/
   • deploy/install/install.sh → /opt/restic-manager/dist/install/install.sh
   • deploy/install/install.ps1 → /opt/restic-manager/dist/install/install.ps1
   • deploy/install/restic-manager-agent.service → /opt/restic-manager/dist/install/restic-manager-agent.service

3. Set --chmod=0755 on the agent binaries and install.sh, --chmod=0644 on the unit file and install.ps1. Distroless final stage runs as nonroot; bundled assets are readable by anyone (mode o+r), so the user switch doesn't break reads.

Verify:

docker build -f deploy/Dockerfile.server -t rm:dev .
docker run --rm -d -p 18080:8080 \
    -e RM_LISTEN=:8080 -e RM_DATA_DIR=/data \
    -e RM_BASE_URL=http://127.0.0.1:18080 \
    -v rm-test:/data rm:dev
curl -fsSL "http://127.0.0.1:18080/agent/binary?os=linux&arch=amd64" | wc -c
curl -fsSL "http://127.0.0.1:18080/install/install.sh" | head -1

Both should succeed against a fresh volume (no operator staging).

---

Slice 4 — Release workflow

.gitea/workflows/release.yml per the spec. Two jobs:

1. image: checkout → setup-qemu → setup-buildx → login → compute tags → buildx build+push.
2. (Future) release-notes: stub left as a TODO comment for now. Operator can hand-write release notes via the Gitea UI on first cut.

The compute tags shell step is the only non-trivial bit; tested inline by running the script with mocked GITHUB_REF_TYPE / GITHUB_REF_NAME env vars before committing.

Verify on first dispatch: trigger workflow_dispatch from the Gitea UI, check the runner produces :snapshot-<sha> and pushes multi-arch.

---

Slice 5 — Tasks.md + commit + push

1. tasks.md: tick P5-03; add a one-line note that goreleaser was dropped in favour of Docker-only after a 2026-05-05 design pass (link the spec).
2. git add -A && git commit -m "p5-03: docker-only release path" (no Co-Authored-By trailer — CLAUDE.md rule).
3. git push -u origin p5-03-docker-release.
4. Stop. Do not open a PR. Wait for operator review.