plonk

plonk is a tiny control-plane API for Docker hosts. It lets a remote caller (for example GitHub Actions over Tailscale) trigger:

• docker compose pull
• docker compose up -d

This is useful when your CI pipeline pushes a fresh image to GHCR and then asks each node to redeploy using its local compose stack.

Features (v0.1)

• Minimal REST API with token auth
• Serialized deploy requests (one deploy at a time)
• Optional pull control (pull on/off)
• Per-request command output returned in the API response

API

GET /healthz

No auth required.

Example response:

{"status":"ok","time":"2026-08-14T12:34:56Z"}

POST /v1/redeploy

Requires a Bearer token in Authorization.

Body:

{
  "pull": true,
  "services": ["api", "worker"]
}

• pull (optional): defaults to server setting (PLONK_ALLOW_PULL)
• services (optional): if omitted, compose applies to all services

Configuration

Environment variables:

• PLONK_BIND_ADDR (default :8080)
• PLONK_SHARED_SECRET (required)
• PLONK_COMPOSE_FILE (default /compose/docker-compose.yml)
• PLONK_PROJECT_DIR (default /compose)
• PLONK_ALLOW_PULL (default true)
• PLONK_COMMAND_TIMEOUT (default 10m, Go duration format)

Run Locally

export PLONK_SHARED_SECRET='replace-me'
export PLONK_COMPOSE_FILE='/absolute/path/to/docker-compose.yml'
export PLONK_PROJECT_DIR='/absolute/path/to/compose/folder'
go run .

Container Usage

plonk needs:

1. Docker CLI + compose plugin in the container
2. Access to the host Docker socket
3. Mounted compose project files

Example:

docker run -d \
  --name plonk \
  --restart unless-stopped \
  -p 8080:8080 \
  -e PLONK_SHARED_SECRET='replace-me' \
  -e PLONK_COMPOSE_FILE='/compose/docker-compose.yml' \
  -e PLONK_PROJECT_DIR='/compose' \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /srv/myapp:/compose \
  ghcr.io/nirima/plonk:0.1.0

GitHub Actions Trigger Example

Call a node over Tailscale after pushing an image:

curl -sS -X POST "http://100.x.y.z:8080/v1/redeploy" \
  -H "Authorization: Bearer ${PLONK_TOKEN}" \
  -H "Content-Type: application/json" \
  --data '{"pull":true}'

GitHub Workflows and GHCR

• /.github/workflows/container.yml builds on PR/main and pushes on non-PR runs.
• /.github/workflows/release.yml builds and pushes on version tags (v*.*.*).
• Both workflows publish multi-arch images: linux/amd64 and linux/arm64.

Package visibility

GHCR packages can default to private on first publish. To auto-switch visibility to public, set a repository secret:

• GHCR_ADMIN_TOKEN: a PAT with package admin permissions for the publishing account.

If this secret is not set, image publish still succeeds but visibility may need to be changed once in GitHub UI.

Security Notes

• Protect network access (for example: Tailscale ACLs/firewall rules).
• Keep PLONK_SHARED_SECRET in a secret manager.
• Mounting /var/run/docker.sock gives broad host control; run only on trusted nodes.