uprade immich to version 3

A few days ago, immich Version 3 was released https://github.com/immich-app/immich/releases#release-v3.0.2. I've been using Version 2 of the media gallery for a long time.
Unfortunately, the previous method using the familiar commands docker compose pull and docker compose up -d --force-recreate failed. The immich-server process reported errors related to a vector engine. The Upgrade Documentation https://docs.immich.app/install/upgrading/ gives me some breadcrumbs to follow.

After doing some research, I found the cause. My Postgres database didn't have the necessary feature. Here, I'll show you how to upgrade from immich v2 to v3. I also just completed the upgrade from Postgres 14 to version 18. I also replaced the Redis cache with valkey.

howto

  1. open your existing docker-compose.yml and change the postgres image to a version that has the needed vector stuff:

    database:
container_name: immich_postgres
# image: registry.hub.docker.com/tensorchord/pgvecto-rs:pg14-v0.2.0@sha256:90724186f0a3517cf6914295b5ab410db9ce23190a2d9d0b9dd6463e3fa298f0
│   image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0
environment:
    POSTGRES_PASSWORD: ${DB_PASSWORD}
    POSTGRES_USER: ${DB_USERNAME}
    POSTGRES_DB: ${DB_DATABASE_NAME}
volumes:
    - pgdata:/var/lib/postgresql
restart: always

  2. recreate and start the containers and wait until immich is up and healthy

    docker compose up -d --force-recreate

  3. stop the containerstack

    docker compose down

  4. change the Variable IMMICH_VERSION in the .env file to v3

    # The Immich version to use. You can pin this to a specific version like "v1.71.0"
IMMICH_VERSION=v3

  5. pull the images and then fire up version 3

    docker compose pull
docker compose up -d --force-recreate

from here on, you have a running instance of immich version 3. However, I think it makes sense to also upgrade the database and the Redis cache to a more recent version.

Optional todos:

upgrade to newer Postgres

  1. create a backup of your Database via the webgui of immich. see https://docs.immich.app/administration/backup-and-restore/ for more Details

    Go to Administration > Job Queues
    Click Create job in the top right
    Select Create Database Backup and click Confirm

the backup may take a while; please wait until it's finished.

  1. check the backuplocation ./library/backups for existing backup of your database.

  2. stop the immich instance with docker compose down

  3. remove the immich_pgdata volume with docker volume rm immich_pgdata

  4. change the database image in the docker-compose.yml and the path of pgdata

    database:
container_name: immich_postgres
# image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0
image: ghcr.io/immich-app/postgres:18-vectorchord0.5.3-pgvector0.8.1
environment:
    POSTGRES_PASSWORD: ${DB_PASSWORD}
    POSTGRES_USER: ${DB_USERNAME}
    POSTGRES_DB: ${DB_DATABASE_NAME}
 volumes:
    - pgdata:/var/lib/postgresql
restart: always

  5. start the database container with docker compose up database -d

  6. restore the backup:

    gunzip --stdout "/path/to/backup/dump.sql.gz" \
| sed "s/SELECT pg_catalog.set_config('search_path', '', false);/SELECT pg_catalog.set_config('search_path', 'public, pg_catalog', true);/g" \
| docker exec -i immich_postgres psql --dbname=<DB_DATABASE_NAME> --username=<DB_USERNAME> --single-transaction --set ON_ERROR_STOP=on  # Restore Backu

  7. start immich stack with `docker compose up -d

Now you should be up and running with Postgres 18.

upgrade redis-cache

  1. replace your redis block in docker-compose.yml file:

    redis:
container_name: immich_redis
image: docker.io/valkey/valkey:9@sha256:4963247afc4cd33c7d3b2d2816b9f7f8eeebab148d29056c2ca4d7cbc966f2d9
healthcheck:
    test: redis-cli ping || exit 1
restart: always

  2. restart the stack docker compose up -d --force-recreate

here is the complete docker-compose.yml

#
# WARNING: Make sure to use the docker-compose.yml of the current release:
#
# https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
#
# The compose file on main may not be compatible with the latest release.
#

name: immich

services:
  immich-server:
    container_name: immich_server
    image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
    volumes:
      - ${UPLOAD_LOCATION}:/usr/src/app/upload
      - /etc/localtime:/etc/localtime:ro
      - /archiv/Bilderplatte/:/archiv
    env_file:
      - .env
    depends_on:
      - redis
      - database
    restart: always
    labels:
      traefik.enable: "true"
      traefik.http.routers.immich.tls.certresolver: "LE"
      traefik.http.routers.immich.tls: "true"
      traefik.http.routers.immich.rule: "Host(`immich.willifix.net`)"
      traefik.http.routers.immich.entrypoints: "websecure"
      traefik.http.routers.immich.middlewares: "rafficontact@docker"
      traefik.http.services.immich.loadbalancer.server.port: 2283
      traefik.docker.network: "immich_default"

  immich-machine-learning:
    container_name: immich_machine_learning
    # For hardware acceleration, add one of -[armnn, cuda, openvino] to the image tag.
    # Example tag: ${IMMICH_VERSION:-release}-cuda
    image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}
    # extends: # uncomment this section for hardware acceleration - see https://immich.app/docs/features/ml-hardware-acceleration
    #   file: hwaccel.ml.yml
    #   service: cpu # set to one of [armnn, cuda, openvino, openvino-wsl] for accelerated inference - use the `-wsl` version for WSL2 where applicable
    volumes:
      - model-cache:/cache
    env_file:
      - .env
    restart: always

  redis:
    container_name: immich_redis
    image: docker.io/valkey/valkey:9@sha256:4963247afc4cd33c7d3b2d2816b9f7f8eeebab148d29056c2ca4d7cbc966f2d9
    healthcheck:
      test: redis-cli ping || exit 1
    restart: always

  database:
    container_name: immich_postgres
    # image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0
    image: ghcr.io/immich-app/postgres:18-vectorchord0.5.3-pgvector0.8.1
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_DB: ${DB_DATABASE_NAME}
    volumes:
      - pgdata:/var/lib/postgresql
    restart: always

volumes:
  pgdata:
  model-cache:

Previous Post Next Post