Webhook-driven Docker Compose service updater. Fills the gap between Watchtower (polling, no CI integration) and full GitOps (Argo CD, Flux) for a self-hosted, single-host environment.

Trigger flow:

Gitea workflow builds and pushes a new image to your registry.
Workflow calls POST /update on this service with the image name.
Service finds the matching Compose-managed container(s) on the host via Docker labels.
Runs docker compose pull + up -d for the relevant service(s).

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: a valid bearer token AND the opt-in label must both be present before any container is touched.

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.

Quick start

Build and push the image (e.g. via your own CI).
Copy docker-compose.example.yml to /home/shcizo/self-hosted/package-updater/docker-compose.yml.
Create .env next to it: UPDATER_API_KEY=$(openssl rand -hex 32).
Point your reverse proxy (NPM/Traefik/Caddy) at package-updater:8080. NPM should handle TLS.
docker compose up -d.
Add the opt-in label se.shcizo.auto-update: "true" to each service you want auto-updated.
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`. Selects the update mechanism for the whole deployment; not mixed per-request.

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.
Single host only in Compose mode. Swarm mode (MODE=swarm) is the multi-node path, but only from a manager node's point of view — the updater itself still needs manager API access (see "Swarm mode" above).
No per-repo API keys: a single shared bearer token is used.