Skip to content

Repo Updater Setup Guide

Andy Gillis edited this page Nov 17, 2026 · 2 revisions

Repo Updater Setup Guide

Introduction

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).

How It Decides What to Upgrade

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 -d on 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 to up that the new commits didn't change.

What It Never Touches

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, and repo-updater itself, 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.

Files

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.

How It's Set Up Here

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: always

Why 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 pull writes 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.

Setup on a Server

  1. Pull the repository so the server has compose/serverX/repo-updater.yaml and its include: line.
  2. 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
  3. Put a Gmail app password in secrets/nas_gmail_app_pass (chmod 600). Mail is sent by scripts/send_mail.sh.
  4. Build and start it:
    docker compose -p mediaserver -f docker-compose-serverX.yaml up -d --build --no-deps repo-updater
  5. Check its log: appdata/repo-updater/updater.log. It should say start: serverX, monthly check at 0109.

Reaching the Page

  • 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.

All Servers on One Homepage

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.

By Hand

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 containers

State 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.

Where Not to Run It

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.

Git Without a Token

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.

Troubleshooting

  • mkdir: can't create directory .../appdata/repo-updater: Permission denied: appdata is 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 status there, 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.

Clone this wiki locally