A watchdog service for Docker environments that automatically repairs compose stacks when their shared VPN network namespace breaks or restarts.
When routing containers or web services through a VPN container like Gluetun (network_mode: container:gluetun), they share Gluetun's network namespace.
If the Gluetun container restarts or updates, this shared network link breaks, causing a network namespace mismatch. The dependent containers immediately lose network connectivity and will either crash or run as offline "zombies" bound to a stale network namespace ID.
Manually resolving this requires stopping and recreating the affected compose stacks to link them to the new namespace container.
The watchdog runs in the background and resolves these failures in two self-healing modes:
- Independent Container Failures: It periodically checks all containers on the host. If a container sharing Gluetun's network namespace crashes, exits, or restarts, the watchdog automatically recreates the stack to restore connectivity.
- Gluetun Restart Events: It monitors Docker events in real-time. If the Gluetun container restarts, the watchdog waits for it to become healthy, then automatically recreates and restarts all dependent stacks.
All configuration is externalized in fix-gluetun.cfg. If the file is missing, the script automatically generates it on its first run with sensible defaults:
DOCKER_ROOT: The root directory where your Docker Compose stacks are located.TARGET_CONTAINER: The name of the Gluetun container to monitor (defaults togluetun).SEARCH_STRING: The pattern in compose files used to identify dependent containers.WATCH_INTERVAL: Interval (in seconds) at which the script checks container health.HEALTH_CHECK_MAX_RETRIES: Maximum retries to wait for Gluetun to recover.HEALTH_CHECK_INTERVAL: Time (in seconds) between health checks.LOG_RETENTION_EVENT_HOURS&LOG_RETENTION_INFO_HOURS: Retain event logs and info logs respectively (in hours).
Manage the service using script flags:
- Check status:
bash fix-gluetun.sh --check - Install as a system service:
sudo bash fix-gluetun.sh --install - Remove service:
sudo bash fix-gluetun.sh --purge - Run in foreground (debug/testing):
bash fix-gluetun.sh --watch
Create a directory for the script and download it using one of the following commands:
Using curl:
mkdir -p fix-gluetun && cd fix-gluetun && curl -sSL https://raw.githubusercontent.com/Arelius-D/fix-gluetun/main/fix-gluetun.sh -o fix-gluetun.sh && chmod +x fix-gluetun.shUsing wget:
mkdir -p fix-gluetun && cd fix-gluetun && wget -q https://raw.githubusercontent.com/Arelius-D/fix-gluetun/main/fix-gluetun.sh -O fix-gluetun.sh && chmod +x fix-gluetun.sh