Unraid Traefik Rolling Update

Zero-downtime updates for the Docker containers you run behind Traefik on Unraid. Tick a container in Settings; from then on Update and Update All on the Docker page start the new version next to the old one, let Traefik switch over once it is healthy, and only then remove the old one. Nothing else to configure: no labels, no healthcheck to write, the template is never modified.

Why

Unraid's own Update stops the container, removes it and recreates it: the site is down for the whole pull and boot, and a broken new version stays broken. Behind a reverse proxy that already load-balances between instances, none of that is necessary.

Features

• Zero downtime: a second instance is started alongside the running one; Traefik routes to it only once Docker reports it healthy, then the old one is stopped. Measured on a real server: 1 or 2 failed requests out of ~500 during the switch (in-flight requests at the very moment the old instance stops), against ~50 with the native stop/start.
• Safe by default: if the new instance never becomes healthy, it is removed and the image tag restored. The running instance is never touched, the "update ready" badge stays, you get a notification with the reason (last healthcheck output included).
• Zero configuration: missing Traefik service / server.port labels and a missing healthcheck are added automatically to the new instance, following Traefik's own rules for default services and ports.
• Optional per-container healthcheck (Coolify-style): scheme, port, path, expected HTTP code, expected response text, interval, timeout, retries, start period. Overrides the image's healthcheck when a path is set.
• Native everywhere else: containers you do not tick keep Unraid's stock Update. Uninstalling the plugin restores the stock behaviour entirely.

Install

Unraid 7.3.0 or later, Traefik with its Docker provider.

Plugins → Install Plugin →

https://raw.githubusercontent.com/Greite/unraid-traefik-rolling-update/main/traefik.rolling.update.plg

Or search for "Traefik Rolling Update" in Community Applications (once listed).

Then open Settings → Utilities → Traefik Rolling Update, set Zero-downtime update to Yes for the containers you want, Apply, and reload the Docker page.

Requirements per container

A ticked container must be able to run twice for a few seconds on the same data (stateless apps, or a database-backed app whose new version has no incompatible migration). Containers that cannot be doubled are listed with the reason and updated the native way:

• it publishes a host port (Traefik does not need one: remove it from the template, put the public URL in the WebUI field instead),
• it has a fixed IP, or runs on the host/none network or in another container's network,
• Tailscale is enabled for it,
• several Traefik services are declared on it while a router has no explicit .service.

How it works

1. Pull the image (nothing else happens if the pull fails).
2. Start <name>.new from the same template, plus what the plugin adds: the Traefik service label the old instance implicitly uses, its port, and a healthcheck if the image has none (or the one you configured). Post Arguments that name the container (docker network connect ... <name>) are applied to <name>.new.
3. Wait for healthy. Traefik ignores containers that are starting or unhealthy, so the new instance receives traffic only once it is ready. Not healthy in time: remove it, restore the image, notify.
4. Stop the old instance (Traefik drops it on the stop event), rename it away, rename <name>.new to <name>.
5. Remove the old container and its image, notify.

Settings

Global: health gate timeout, and which notifications you want (success, warnings, errors).

Per container: Zero-downtime update Yes/No, and an optional HTTP healthcheck. With a path, the new instance is healthy only when GET scheme://127.0.0.1:port/path answers the expected code (default: any 2xx or 3xx) and, if given, contains the expected text. It runs curl inside the container (wget as a fallback, 2xx only). Without a path, the automatic probe applies only when the image has no healthcheck.

Everything is stored in /boot/config/plugins/traefik.rolling.update/traefik.rolling.update.cfg (INCLUDE, HEALTHCHECKS, TIMEOUT, NOTIFY, NOTIFY_WARNING, NOTIFY_ERROR).

Support

Bug reports and questions: GitHub issues. Please include the output shown in the update window and your container's Traefik labels.

Development

make selftest                    # pure-logic checks, local PHP, no Docker
bash scripts/test_php_syntax.sh  # php -l on the script, the include and the .page files
bash scripts/test_build.sh       # build dist/traefik.rolling.update-0000.00.00.txz + verify contents
make deploy                      # rsync to a test server (git-ignored local.mk: HOST=...)

Releases: Actions → Release → Run workflow. See CONTRIBUTING.md.

License

GPL-2.0. The five *_nchan helpers in scripts/rolling_update are verbatim copies from Unraid's dynamix.docker.manager (Copyright Lime Technology / Bergware International, GPL-2.0).