Synology-friendly Immich Docker Compose upgrade helper

[jj12883]

Hi all — I’ve published a small helper script to safely upgrade an Immich Docker Compose stack.

It was written and tested primarily on Synology DSM 7, but should work on most Linux hosts running Docker Engine + Docker Compose v2.

Key features:

• Dry-run by default (explicit --run required)
• Confirmation string includes the Compose project name
• Optional Postgres backup via in-container pg_dump
• Compose validation before any destructive actions
• Label-checked cleanup to avoid cross-stack container issues
• Graceful Ctrl-C handling with recovery hints

Release (v0.0.8):
https://github.com/jj12883/immich-docker-upgrade/releases/tag/v0.0.8

Repo:
https://github.com/jj12883/immich-docker-upgrade

Notes:

• Targets Compose v2 (docker compose), not legacy docker-compose
• Community-maintained — I’m unlikely to actively maintain it, but forks/PRs welcome

Hope it’s useful for anyone managing Immich Docker installs.

[keesjebal]

Thanks, that sounds great!

I'm trying to run it, but I got an error in the script:

***:/volume1/docker/Immich# ./immich-upgrade.sh --run --verbose
2026-02-02 11:26:16 [STEP] 1. Preflight checks
2026-02-02 11:26:16 [OK] ✔ Found docker-compose.yml and .env
2026-02-02 11:26:16 [OK] ✔ Folder sanity check: OK
./immich-upgrade.sh: line 329: local: can only be used in a function
2026-02-02 11:26:17 [----] ------------------------------------------------------------
2026-02-02 11:26:17 [ERR] ✖ Upgrade failed (exit 1) at line 329
2026-02-02 11:26:17 [ERR] ✖ Last action: Preflight checks
2026-02-02 11:26:17 [ERR] ✖ Command: local _logdir="$SCRIPT_DIR/logs"
2026-02-02 11:26:17 [ERR] ✖ Recovery hints:
2026-02-02 11:26:17 [ERR] ✖ - Status: docker compose ps
2026-02-02 11:26:17 [ERR] ✖ - Logs: docker compose logs --tail=200
2026-02-02 11:26:17 [ERR] ✖ - Retry: ./immich-upgrade.sh --run --verbose
2026-02-02 11:26:17 [ERR] ✖ - If stuck: docker compose down && docker compose up -d
2026-02-02 11:26:17 [----] ------------------------------------------------------------

I'm having an up-to-date Synology with the latest Immich version (v2.5.2).