Repository navigation
Repo Updater Setup Guide
When you run several servers from one repository, the hard part isn't making a change; it's remembering to log in to every server afterwards to git pull and recreate the right containers. Remote servers (family members' NASes, a cabin PC) can go months without an update.
repo-updater is a small container that runs on each server and does this for you:
- Once a month it pulls the repository. That only changes files: nothing restarts.
- It works out exactly which containers the new commits change on that server, and emails you a list with a Review & upgrade button.
- The button opens a page with two buttons side by side:
- Pull from GitHub now pulls straight away, so you don't have to wait for the monthly check after pushing a change, and shows what changed.
- Upgrade recreates only the listed containers, then emails you the result. It's greyed out until a pull finds something to upgrade.
Images are not its job: Watchtower Setup Guide keeps updating images as before. repo-updater handles changes to the compose files (settings, new services, pinned versions).
Before and after each pull, the container runs docker compose config --hash for every service, with the same Compose version both times. A service counts as changed only if its hash is different after the pull. So the list contains only what the new commits changed, and never older differences between the running containers and the repository.
Lesson learned: an earlier version ran
docker compose up -don every running service and trusted Compose to leave the unchanged ones alone. It didn't: Compose recreated 16 containers whose settings hadn't changed. Containers that Watchtower has updated look different to Compose. Never pass services toupthat the new commits didn't change.
Some containers are never upgraded from the button, because a bad change there can lock everyone out, or because they have their own deploy steps:
-
cloudflared,guacamole,guacd, andrepo-updateritself, by default. - Anything else you add to
REPO_UPDATE_SKIP(shell patterns are allowed, e.g.myapp-*for an app with its own migrations).
If a commit changes one of these, the email lists it under "Changed, do by hand".
Containers that share another container's network (network_mode: service:gluetun) are recreated together with it automatically; otherwise they'd lose their network.
scripts/repo-updater/
├── Dockerfile # docker CLI + Compose + git + curl + BusyBox httpd
├── lib.sh # shared settings, HTML email helpers
├── check.sh # the monthly pull (also: --quiet for the page, --resend)
├── apply.sh # the Upgrade button
├── run.sh # container entrypoint: web page + monthly timer
└── www/cgi-bin/update # the page
compose/templates/repo-updater.yaml
compose/serverX/repo-updater.yaml
The scripts are mounted from the repository, not copied into the image, so a pull updates them without a rebuild.
services:
repo-updater:
container_name: repo-updater.${HOST_NAME}
build: ${BASE_DIR}/scripts/repo-updater
image: repo-updater:local
command: sh ${BASE_DIR}/scripts/repo-updater/run.sh
user: "${PUID}:${PGID}"
group_add:
- "${DOCKER_GID:-0}" # group that owns /var/run/docker.sock
environment:
TZ: ${TZ}
SERVER: server3 # this server's folder under compose/
HOST_NAME: ${HOST_NAME}
BASE_DIR: ${BASE_DIR}
CHECK_AT: "0109" # day of month + hour: the 1st at 09:00
UPDATE_URL: ${REPO_UPDATE_URL}
REPO_UPDATE_KEY: ${REPO_UPDATE_KEY}
MAIL_TO: ${REPO_UPDATE_MAIL_TO}
NAS_MAIL_PASS_FILE: ${SECRETSDIR}/nas_gmail_app_pass
ports:
- "${REPO_UPDATE_PORT:-8099}:8080"
volumes:
- ${BASE_DIR}:${BASE_DIR} # same path as on the host
- /var/run/docker.sock:/var/run/docker.sock
working_dir: ${BASE_DIR}
restart: alwaysWhy it's set up this way:
- The repository is mounted at the same path as on the host. Compose sends bind-mount paths to the Docker daemon, which resolves them on the host, so they have to match.
-
It runs as your normal user, with the Docker socket's group added. Files that
git pullwrites stay owned by you, not by root. - It checks at 09:00 on the 1st, a few hours after Watchtower's monthly run at 06:00.
- The page runs on BusyBox httpd with a small CGI script. There's no framework to keep updated.
- Pull the repository so the server has
compose/serverX/repo-updater.yamland itsinclude:line. - Add to that server's
.env:REPO_UPDATE_KEY=<random, e.g. openssl rand -hex 32; the same key on every server is simplest> REPO_UPDATE_MAIL_TO=you@example.com REPO_UPDATE_URL=https://deploy.example.com/cgi-bin/update DOCKER_GID=0 # ls -ln /var/run/docker.sock; 0 on QNAP
- Put a Gmail app password in
secrets/nas_gmail_app_pass(chmod 600). Mail is sent byscripts/send_mail.sh. - Build and start it:
docker compose -p mediaserver -f docker-compose-serverX.yaml up -d --build --no-deps repo-updater
- Check its log:
appdata/repo-updater/updater.log. It should saystart: serverX, monthly check at 0109.
-
Through that server's own tunnel: add an ingress rule, e.g.
deploy.example.com → http://repo-updater.<host>:8080. Keep it behind Cloudflare Access: Zero Trust. -
No tunnel on that server: the page is published on the LAN at port 8099. Another server's tunnel can route to it, e.g.
pi-deploy.example.com → http://192.168.1.11:8099.
The page also requires the key. The email's button and the Homepage links carry it.
On the main server's Homepage, an Updates group in services.yaml links to every server's page. With the same key on every server, one variable covers all the links:
- Updates:
- server1:
icon: git.png
href: https://deploy.example.com/cgi-bin/update?key={{HOMEPAGE_VAR_REPO_UPDATE_KEY}}
- server3:
icon: git.png
href: https://pi-deploy.example.com/cgi-bin/update?key={{HOMEPAGE_VAR_REPO_UPDATE_KEY}}Add HOMEPAGE_VAR_REPO_UPDATE_KEY: ${REPO_UPDATE_KEY} to Homepage's environment.
docker exec repo-updater.<host> sh <BASE_DIR>/scripts/repo-updater/check.sh # pull and email now
docker exec repo-updater.<host> sh <BASE_DIR>/scripts/repo-updater/check.sh --resend # email the pending list again
docker exec repo-updater.<host> sh <BASE_DIR>/scripts/repo-updater/apply.sh # upgrade the pending containersState lives in appdata/repo-updater/: pending.txt lists the containers waiting to be upgraded, updater.log holds the history, and last-apply.txt holds the output of the last upgrade.
Not on machines where you make changes and push them, such as your desktop or laptop. A Windows checkout also uses different line endings than the container's git, so the container would see every file as changed.
The repository is public, so pulling needs no login. On start, the updater sets the fetch address to the plain https://github.com/... URL, which also cleans up old remote URLs that had a token in them. A server that also pushes should use an SSH deploy key that only works on this repository (repository → Settings → Deploy keys, with write access). Don't use a personal access token in the remote URL.
-
mkdir: can't create directory .../appdata/repo-updater: Permission denied:appdatais owned by root on that server. Create the folder once and give it to your user:docker exec -u 0 repo-updater.<host> sh -c "mkdir -p <BASE_DIR>/appdata/repo-updater && chown <PUID>:<PGID> <BASE_DIR>/appdata/repo-updater" -
The pull fails: someone edited a tracked file on that server. Look at
git statusthere, then commit the change from your desktop or undo it on the server. - Upgrade stays grey after a pull: the new commits don't change any container on that server. The page says so.
- The page shows "Current authentication token is expired": the Cloudflare login page sat open too long. Open the link again.
- On a Raspberry Pi: the image builds for ARM automatically. The first build takes a few minutes.