package-updater/README.md

package-updater

Webhook-driven Docker service updater — Compose stacks or Swarm services. Fills the gap between Watchtower (polling, no CI integration) and full GitOps (Argo CD, Flux) for self-hosted environments, one instance per server.

Trigger flow:

1. Gitea workflow builds and pushes a new image to your registry.
2. Workflow calls POST /update on this service with the image name.
3. Service finds the matching container(s) or Swarm service(s) via Docker labels.
4. Runs docker compose pull + up -d, or docker service update, depending on MODE.

See design spec and implementation plan for full design and rationale.

How it finds the right stack

The service queries the Docker socket and reads the labels Compose itself attaches to every container:

• com.docker.compose.project
• com.docker.compose.service
• com.docker.compose.project.working_dir
• com.docker.compose.project.config_files

A container is eligible for update only if it has both:

• An image name matching the request (tag-agnostic), AND
• The opt-in label se.shcizo.auto-update=true.

Defense in depth, compose mode: a valid bearer token AND the opt-in label AND a working directory inside STACKS_ROOT must all hold before a container is touched. A stack outside STACKS_ROOT comes back as refused rather than being updated.

Swarm mode's gate is the token and the opt-in label only — a Swarm service has no local compose file to anchor a path check against.

Swarm mode

Set MODE=swarm to update Docker Swarm services instead of Compose stacks. The service runs docker service update --image via the Docker API instead of shelling out to docker compose.

Two things to get right when running in Swarm mode:

• The opt-in label goes on the service, not the container/task. Swarm mode reads Service.Spec.Labels, so add it with docker service update --label-add se.shcizo.auto-update=true <service> or set it under deploy.labels in the stack file — a plain labels: entry on the service (container-level) is not visible to Swarm mode's discovery.
• The updater must talk to a Swarm manager. docker service update requires manager API access, so either point DOCKER_HOST at a manager node or schedule the updater container itself on a manager with the socket mounted. This is a deployment concern the service cannot detect or work around.

Deploying across multiple servers

An instance can only reach the Docker daemon it is configured against. It cannot update stacks on other machines. The deployment model follows from that:

One instance per server. Each server runs its own package-updater against its own local Docker socket, with MODE set to whatever that machine runs:

Server	MODE	Updates
Swarm manager node	swarm	All Swarm services in the cluster
Standalone Compose host	compose	Compose stacks on that host

CI fans out. The Gitea composite action takes a list of endpoints and posts /update to every instance, so one workflow run reaches the whole fleet. Each instance answers for its own machine; there is no aggregated cross-server response and no instance coordinates any other.

This is why MODE is exclusive rather than a mode that handles both at once: an instance that could do both would still only reach one daemon, so the extra generality buys nothing.

Quick start

1. Build and push the image (e.g. via your own CI).
2. Copy docker-compose.example.yml to /home/shcizo/self-hosted/package-updater/docker-compose.yml.
3. Create .env next to it: UPDATER_API_KEY=$(openssl rand -hex 32).
4. Point your reverse proxy (NPM/Traefik/Caddy) at package-updater:8080. NPM should handle TLS.
5. docker compose up -d.
6. Add the opt-in label se.shcizo.auto-update: "true" to each service you want auto-updated.
7. Use the Gitea composite action in your repos to call /update after a build.

Configuration

All via environment variables.

Variable	Required	Default	Purpose
UPDATER_API_KEY	yes	—	Bearer token. Service refuses to start without it.
STACKS_ROOT	no	/home/shcizo/self-hosted	Required parent for any stack eligible to update.
PORT	no	8080	HTTP listen port.
LOG_LEVEL	no	info	debug / info / warn / error.
UPDATE_TIMEOUT	no	5m	Per-job timeout (Go duration).
OPT_IN_LABEL	no	se.shcizo.auto-update	Label name to check; value must equal "true".
MODE	no	compose	compose or swarm. Which paradigm this instance's Docker daemon runs. See Deploying across multiple servers.

Endpoints

Endpoint	Auth	Purpose
POST /update	Bearer token	Trigger pull + restart for matching services
GET /healthz	none	Liveness + Docker socket reachability
GET /version	none	Build info
GET /metrics	none	Prometheus exposition

/healthz, /version, and /metrics are intentionally unauthenticated — they're internal-network only behind the reverse proxy.

Observability

• Logs: JSON to stdout, picked up by Promtail/Alloy → Loki.
• Metrics: Prometheus exposition on /metrics. Notable: package_updater_update_jobs_total{project,service,status}, package_updater_last_update_timestamp{project,service}, package_updater_docker_ping_up.

Development

go test ./...
go build ./cmd/server
docker build -t package-updater:dev .

Known v1 gaps

These are tracked in the spec's section 2 and section 15 as deliberate out-of-scope:

• Self-update wiring: internal/selfupdate.Wrapped exists and is unit-tested but is not wired into the live queue. The HTTP response flush ordering for self-replacement is a future enhancement; for now, expect to manually rerun docker compose up -d on the host if pushing a new image of package-updater itself causes a mid-response interruption.
• No rollback: Compose's "keep old container if new fails to start" is the only safety net.
• One instance reaches one daemon. An instance never updates another server; fleets run one instance per server with CI fanning out to all of them (see "Deploying across multiple servers"). Swarm mode is the exception in that a single manager-node instance covers the whole cluster.
• No per-repo API keys: a single shared bearer token is used.