Varaverk/Docker_Essentials/Manual-Docker_Essentials.md

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🐳 DOCKER ESSENTIALS — Manual

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Configuration reference, setup procedures, and operational workflows. For folder overview and design philosophy see README-Docker_Essentials.md. For per-script detail see the script headers directly.

Watchdog configuration has moved. docker_watchdog.sh is now in Watchdogs/. Memory limits, CPU thresholds, HTTP health checks, dependency ordering, skip list recovery, and all watchdog config vars are in Watchdogs/Manual-Watchdogs.md.

---

━━━ RESTART SCHEDULE CONFIGURATION ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

---

── Daily Restart List ───────────────────────────────────────────────────────

# host1.conf
# Restarted every night at 1am via daily_sync_maintenance.sh.
#
# Good candidates:
#   Reverse proxies         — connection table fills slowly over weeks
#   Authentication services — session cache benefits from periodic clearing
#   Live TV schedulers      — accumulated scheduling state slows decisions
#   Download managers       — connection pool maintenance
#
HOST1_DAILY_RESTART_CONTAINERS=(
    "NginxProxyManager"     # connection table fills slowly over weeks
    "Authelia"              # session cache benefits from periodic clearing
    "Dispatcharr"           # Live TV scheduler accumulates state
    "Dispatcharr-Basic"     # secondary Live TV scheduler — same reason
    "ErsatzTV-Emby"         # channel schedule builder, stale entries accumulate
)

This list also drives docker_update.sh in normal mode — containers added here get their images updated daily before the restart. Add a container once, it gets both.

---

── Weekly Restart List ──────────────────────────────────────────────────────

# host1.conf
# Restarted every Sunday at 2:30am via weekly_sync_maintenance.sh.
# Runs AFTER the sync window's own restart of critical containers (Emby, auth stack).
#
# Daily vs Weekly decision:
#   Daily:  connection-heavy infrastructure — degrades faster (proxy, auth, Live TV)
#   Weekly: productivity and media services — degrades slowly (NextCloud, AdGuard, Immich)
#
HOST1_WEEKLY_RESTART_CONTAINERS=(
    "NextCloud"       # file sync — benefits from clean weekly start
    "AdGuard-Home"    # DNS — cache and stat accumulation
    "Immich"          # photo library — index/cache maintenance
)

---

━━━ NETWORK CONFIGURATION ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

# host1.conf
# Networks to ensure exist + containers to connect to each network.
# Many-to-many: every container connects to every network listed.
#
# Containers do not need to be running — script handles missing containers
# gracefully (warns + skips). They connect on the next array start.
#
HOST1_NETWORK_CONNECT_NETWORKS=(
    "high-availability"     # main internal network — most containers should be on this
)

HOST1_NETWORK_CONNECT_CONTAINERS=(
    "memcached"             # NextCloud's cache — needs to reach NextCloud AIO network
    "Npm-CrowdSec"          # CrowdSec bouncer — needs to reach NPM's network
)

Timing dependency: Networks created by Docker Compose stacks (e.g. NextCloud AIO) only exist after those stacks start. If this script runs before the Compose stack, the network won't exist yet and the connection fails this run. It will succeed on the next array start. Schedule Compose stacks early in ARRAY_START_SCRIPTS order to minimise the window.

---

━━━ CONTAINER UPDATE CONFIGURATION ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

# master.conf
DAILY_CONTAINER_UPDATES=true     # enable/disable daily image pull
                                  # docker_daily_restart.sh still runs regardless
                                  # update and restart are independent

WEEKLY_REMAINING_UPDATES=true    # enable/disable weekly remainder pull + prune
                                  # to disable: set false or remove from WEEKLY_MAINTENANCE_SCRIPTS

docker_update.sh in normal mode targets DAILY_RESTART_CONTAINERS — the same list used by docker_daily_restart.sh. No second list to maintain.

docker_update_remaining.sh derives its target list automatically: all running containers minus DAILY_RESTART_CONTAINERS minus WEEKLY_RESTART_CONTAINERS. Everything gets updated at least once per week with no explicit configuration.

---

━━━ FULL CONFIGURATION REFERENCE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

── host*.conf ────────────────────────────────────────────────────────

# Per-host — varies between HOST1 and HOST2

# Daily restart list (also drives docker_update.sh normal mode)
HOST1_DAILY_RESTART_CONTAINERS=()

# Weekly restart list
HOST1_WEEKLY_RESTART_CONTAINERS=()

# Networks to ensure exist
HOST1_NETWORK_CONNECT_NETWORKS=()

# Containers to connect to every configured network
HOST1_NETWORK_CONNECT_CONTAINERS=()

# Watchdog config (memory limits, HTTP checks, required, dependencies):
# → see Watchdogs/Manual-Watchdogs.md

---

── master.conf ──────────────────────────────────────────────────────────────

# Shared — applies to both servers

# ── Container updates ──────────────────────────────────────────────────
DAILY_CONTAINER_UPDATES=true
WEEKLY_REMAINING_UPDATES=true

# ── Retry behaviour (shared by restart scripts) ────────────────────────
RETRY_COUNT=3                        # retry attempts before marking failed
SLEEP=5                              # seconds between retry attempts

# Watchdog thresholds (CPU, memory, HTTP, restart loop):
# → see Watchdogs/Manual-Watchdogs.md

---

━━━ PROCEDURES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

── Adding a Container to Monitoring ────────────────────────────────────────

Adding a container to watchdog monitoring is purely additive — add lines to host*.conf. No script changes. detect_hosts() picks up the new config on the next watchdog cycle. See Watchdogs/Manual-Watchdogs.md for the full procedure.

To add a container to daily restarts (and daily image updates):

# host1.conf
HOST1_DAILY_RESTART_CONTAINERS=(
    ...existing...
    "MyApp"    # also adds it to the daily image update
)

To exclude a container from Tier 2 global scan (e.g. one-shot that exits normally):

# master.conf
WATCHDOG_SCAN_IGNORE=(
    "MyApp"    # one-shot — exits cleanly, don't treat as crash
)

---

── Skip List Recovery ────────────────────────────────────────────────────────

When docker_watchdog.sh skip-lists a container, use Tools/watchdog_skip_list_manager.sh. Full procedure in Watchdogs/Manual-Watchdogs.md.

Tools/watchdog_skip_list_manager.sh --status          # see skip list + container states
Tools/watchdog_skip_list_manager.sh --clear MyApp     # clear after fixing root cause
Tools/watchdog_skip_list_manager.sh --clear-all       # clear everything

---

━━━ FLAG REFERENCE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

All scripts support these standard flags:

Flag	What it does
--dry-run	Preview actions without making changes. Shows exactly what would happen.
--status	Show current config, container states, and relevant runtime info, then exit.
--log	Verbose mode — adds per-container banners, action lines, pull output, and list details.

Output tiers: Without --log, each script processes silently and concludes with a summary block: identity, duration, counts, and a status line. Per-container detail only appears with --log. Warnings and errors are always visible regardless of --log.

docker_update.sh --remainder

Switches to remainder mode — updates all running containers not in the managed daily/weekly lists. Called by weekly_sync_maintenance.sh. Can be run manually to sweep containers that haven't been updated recently.