{"id":429,"date":"2026-08-31T07:45:00","date_gmt":"2026-08-31T05:45:00","guid":{"rendered":"https:\/\/www.lukaswojcik.com\/?p=429"},"modified":"2026-10-24T01:39:04","modified_gmt":"2026-10-23T23:39:04","slug":"local-ci-cd-for-raspberry-pi-automating-docker-compose-deployments","status":"publish","type":"post","link":"https:\/\/www.lukaswojcik.com\/blog\/en\/raspberry-pi\/local-ci-cd-for-raspberry-pi-automating-docker-compose-deployments\/","title":{"rendered":"Local CI\/CD for Raspberry Pi: Automating Docker Compose Deployments"},"content":{"rendered":"
A local CI\/CD pipeline can test changes and deploy Docker Compose services on a Raspberry Pi without a separate SSH session for every update. Git stores the deployment definition; a local worker applies an approved version. Backups, monitoring and recovery procedures remain necessary.<\/p>\n
1. Define a reproducible release<\/h2>\n
CI means automated integration checks; CD covers delivery or deployment. A webhook starts a job, but does not provide those checks by itself. In a GitOps approach, Git records the desired configuration and an automated process reconciles the running services with that configuration.<\/p>\n
\n
Configuration:<\/strong> Compose describes services, networks and volume mounts. Volume contents and database records are separate data, not part of the YAML file. Secrets belong outside an ordinary Git repository.<\/li>\n
Release identity:<\/strong> The exact Git commit and image digests identify the release. A moving tag such as :latest<\/code> does not identify a reproducible release.<\/li>\n
Recovery:<\/strong> Git history helps trace changes, but is not inherently immutable. Restoring an older configuration does not reverse database migrations or restore deleted files. Backups and a tested recovery path are separate requirements.<\/li>\n<\/ul>\nAuthenticate the request, authorize the target, deploy a fixed release and check the application.<\/figcaption><\/figure>\n
2. Validate the webhook before deployment<\/h2>\n
A listener such as adnanh\/webhook<\/code> receives the repository event. For GitHub, validation of X-Hub-Signature-256<\/code> uses the unchanged request body, the webhook secret and a constant-time comparison. HMAC verifies the signed payload; deployment permission still requires explicit checks of the event, repository and allowed branch.<\/p>\n\n
Invalid or disallowed requests are rejected. Recorded delivery IDs help detect duplicate deliveries and prevent repeated execution.<\/li>\n
A validated job enters a queue without Docker access. Arbitrary payload fields must not become shell commands.<\/li>\n
A separate worker fetches the approved commit into a controlled release directory. Serialized deployments prevent concurrent changes to the same stack.<\/li>\n
The worker validates the complete Compose configuration, prepares images through an explicit pull or build step, and then starts the release.<\/li>\n<\/ol>\n
docker compose up -d --remove-orphans<\/code> alone is not a complete deployment pipeline. Existing services with changed images or configuration are recreated; a newer image behind an unchanged remote tag is not guaranteed to be fetched by that command. The pull policy or a separate pull step must be deliberate. The Compose project name and the set of configuration files must remain consistent.<\/p>\n
3. Check service health and plan recovery<\/h2>\n
docker compose up --wait --wait-timeout 120<\/code> waits for services to be running or healthy and implies detached mode. The 120-second limit is an example, not a universal startup allowance. A service without a health check is only checked for running state.<\/p>\n
Docker HEALTHCHECK<\/code> reports health after the configured intervals and retries. An unhealthy<\/code> status alone does not trigger a restart or rollback in ordinary Docker Compose. The deployment worker needs an explicit failure policy, application-level checks and useful logs. A green process status does not establish that login, storage or database access works.<\/p>\n
Local ARM builds can avoid cross-compilation, provided base images and dependencies support the target architecture. Builds also consume CPU, memory and storage on the Pi.<\/p>\n
4. Separate network access from deployment authority<\/h2>\n
The network-facing listener should run without root privileges and without Docker socket access. Membership in the docker<\/code> group grants root-level authority over a conventional rootful Docker daemon. A read-only socket proxy supports inspection, but cannot perform a deployment that changes containers.<\/p>\n
A small privileged worker can accept only validated jobs for fixed repositories and deployment targets. Repository-controlled Compose files can still request powerful mounts or privileges, so the trusted code and configuration boundary matters. A management VLAN with firewall rules reduces reachable paths; isolation does not guarantee protection from compromised devices in an allowed network.<\/p>\n
5. GitHub Actions and restricted SSH keys<\/h2>\n
A GitHub-hosted runner can reach the Pi over SSH through an authenticated private network or VPN; a publicly exposed SSH port is not inherently required. A self-hosted runner instead requests jobs from GitHub. The current reference lists Linux ARM64, but no longer lists ARM32. OS, architecture and individual action compatibility need checking before installation.<\/p>\n
The runner needs outbound HTTPS on port 443 to GitHub; jobs may additionally need Git, registry and application connections. No inbound port is required for job assignment. A private repository does not make arbitrary workflow code trustworthy. Untrusted pull-request code must not run with deployment credentials or production Docker access.<\/p>\n
A dedicated deployment key can use the following authorized_keys<\/code> pattern. AAAA\u2026<\/code> is a placeholder for a complete public key:<\/p>\n
command=<\/code> forces the configured command; restrict<\/code> disables forwarding, PTY allocation and ~\/.ssh\/rc<\/code>. The script must reject untrusted arguments, including SSH_ORIGINAL_COMMAND<\/code>, and protect its dependencies and configuration from modification by the caller. A stolen key can still repeatedly trigger the permitted operation; a forced command is not a complete security boundary.<\/p>\n
6. Scheduled image updates<\/h2>\n
The original containrrr\/watchtower<\/code> repository was archived on 17 December 2025. Community forks such as nickfedor\/watchtower<\/code> need a separate version and Docker API compatibility check before migration. Image polling recreates containers from newer images; it does not test application compatibility.<\/p>\n
The linked Watchtower v1.14.3 reference documents a default polling interval of 86,400 seconds and a six-field WATCHTOWER_SCHEDULE<\/code>. 0 0 4 * * *<\/code> schedules 04:00; an explicit TZ=Europe\/Warsaw<\/code> makes the intended local time clear. The documented default timezone is UTC. Schedule and WATCHTOWER_POLL_INTERVAL<\/code> are alternatives.<\/p>\n
WATCHTOWER_LABEL_ENABLE=true<\/code> selects containers carrying com.centurylinklabs.watchtower.enable=true<\/code>. WATCHTOWER_CLEANUP=true<\/code> removes old images after updates, but does not manage all logs or volume data and may remove a locally available rollback image. Each service needs one update mechanism: independently changing the same container through GitOps and Watchtower can produce conflicting states.<\/p>\n
\n
Questions and answers<\/h2>\n
Can a read-only Docker proxy deploy a Compose stack?<\/h3>\n
No. Creating, stopping or replacing containers needs write operations. The useful separation is a listener without Docker access and a controlled worker with the required authority. The worker still needs input validation, trusted configuration, deployment locking and audit logs.<\/p>\n<\/div>\n
![\"Validated](\"https:\/\/www.lukaswojcik.com\/blog\/wp-content\/uploads\/diagrams\/dia-429-cicd-20261024.png\")