Immich upgrade lab

Test Immich upgrades in a sandbox to avoid surprise during a real upgrade.

Overview | How to use | Getting help | Caveats

Overview

A tool/sandbox for testing Immich version upgrades.

This tool automates validation of upgrade paths: it deploys the initial version in a sandbox and performs an upgrade to the target version. (Post-upgrade e2e tests to be implemented in the future).

It tests two upgrade scenarios:

• from old version to new version + old compose
• from old version to new version + new compose

Step by step execution of the script:

1. Initial version. The sandbox can be created from scratch (empty), from an existing snapshot, from data of an existing Immich instance (library, postgres). It's possible to interact with the sandbox (open Immich UI, change settings, populate with assets) before performing an upgrade.

• It deploys the initial version.
• You do initial setup and add some files to the sandbox.
• Then it creates a snapshot.

2. Refreshing the sandbox.

Before each upgrade test a fresh sandbox instance is created/restored from a snapshot (step 1).

3. Upgrade (to target version)

• Next, one by one, it tries requested upgrade paths in a sandbox.
  • Each time from a fresh test instance restored from snapshot.
  • Currently it tests two upgrade scenarios: (1) new version + old compose, (2) new version + new compose.
  • Apart from that, other modifications are possible in principle (e.g. testing custom changes in docker compose file) but not implemented yet.
• After each upgrade it pauses and waits until you interact with the upgraded instance (check UI and logs) to validate the upgrade outcome.

How to use

Quick start

1. Download test-upgrade.sh from Github and make the script executable: chmod +x path/to/test-upgrade.sh
2. Go to an empty directory.
3. Run the script with two arguments: "from" and "to" versions for testing upgrade between. Follow the on-screen instructions.

Example:

# upgrade from v1.123.0 to v1.132.3
./test-upgrade.sh v1.123.0 v1.132.3

Sandbox for an existing Immich instance

Run sandbox and try upgrades using data from the existing Immich.

Assume the layout with two separate directories - /app/immich for compose and /data/immich for persistent data.

Directory trees for (1) compose, (2) persistent data

tree -a -L 1/app/immich

/app/immich
├── compose.override.yaml
├── compose.yaml
├── conf
└── .env

tree -L 2 /data/immich

/data/immich
├── library
│   ├── backups
│   ├── encoded-video
│   ├── library
│   ├── profile
│   ├── thumbs
│   └── upload
└── postgres
    ├── base
    ...
    └── postmaster.pid

This will copy all your Immich data into a sandbox/snapshot before performing an upgrade.

./test-upgrade.sh v1.125.7 v1.132.3 \
  --from-compose /app/immich \
  --from-data /data/immich/library \
  --from-postgres /data/immich/postgres

Sandbox for an existing remote Immich instance (with rsync)

Copy thumbnails and copy Postgres from the existing instance. Use the release compose instead of the existing one (omiting --from-compose).

./test-upgrade.sh v1.140.1 v1.140.1 \
  --from-data immich.internal:/dc/data/immich/library \
  --from-data-opts "-v --include=.immich --include=thumbs/** --include=*/ --exclude=* --prune-empty-dirs" \
  --from-postgres immich.internal:/dc/data/immich/postgres

Getting help

Check the usage instructions by providing --help / -h or simply run it without arguments:

/path/to/test-upgrade.sh --help

Immich upgrade in a sandbox

Performs upgrade from version ver1 to version ver2 in a sandbox.
It tests two upgrade scenarios: (1) new version + old compose, (2) new version + new compose.

The test instance (sandbox) can be created:
  - from scratch (empty) using default/release compose
  - from a previously created snapshot
  - using existing Immich instance's compose+data+postgres
By default, when no optional args are specified, the sandbox is created from this version's snapshot if exists, otherwise from scratch.

Both versions (from and to) are mandatory arguments.

Usage:
  ./test-upgrade.sh <ver1> <ver2>                   # Upgrade from version1 to version2
  ./test-upgrade.sh --from <ver1> --to <ver2>       # Upgrade from version1 to version2 (flags form)
  ./test-upgrade.sh <ver1> <ver2> [--args ...]      # Upgrade with extra args
  ./test-upgrade.sh --help                          # Show this help

Optional arguments:
  --from-compose <dir>    Use compose files from specified location when creating sandbox.
  --from-data <dir>       Use (copy) Immich data (library) from specified location when creating sandbox.
  --from-postgres <dir>   Use (copy) Postgres data from specified location when creating sandbox.

Examples:
  ./test-upgrade.sh v1.123.0 v1.132.3
  ./test-upgrade.sh --from v1.123.0 --to v1.132.3

Caveats

This is an early version, PoC for immich-app/immich#20847.