Skip to content

Immich Immich

Description / nameInput element
Container Registry
Container Configuration Root Path
Timezone

Build Status Last Commit

High performance self-hosted photo and video management solution.
Daemonless daemonless/immich
Source immich-app/immich
Website immich.app

Version Tags

These tags apply to the immich-server image (set via IMMICH_TAG):

Tag Description Best For
latest Current stable release, built from the latest upstream Immich release. Most users.
beta Beta release built from upstream v3.0.0-rc.0. Testing upcoming releases early.

Machine learning (immich-ml, set via IMMICH_ML_TAG) follows the same latest and beta tags.

immich-postgres:latest and :14 are both PostgreSQL 14, matching upstream Immich. New installs can use :18; upgrading an existing database needs a full dump and restore.

Parts

Service Image Role
immich-server ghcr.io/daemonless/immich-server:${IMMICH_TAG:-latest} Web UI and API docs
immich-machine-learning ghcr.io/daemonless/immich-ml:${IMMICH_ML_TAG:-latest} Faces, objects and smart search (ONNX, CPU) docs
immich-public-proxy ghcr.io/daemonless/immich-public-proxy:latest Public links to albums, without exposing the server (with proxy) docs
redis ghcr.io/daemonless/redis:latest Cache and job queue docs
database ghcr.io/daemonless/immich-postgres:latest PostgreSQL with pgvector, for the ML embeddings docs

Before deploying, ensure your host environment is ready. See the Quick Start Guide for host setup instructions, including the security model for host vs. container privileges.

Deployment

Machine learning Faces, objects and smart search. Needs 2 GB of RAM and downloads about 1 GB of models on first run.

Public sharing Share albums with people who have no account, without exposing Immich itself.

immich-server:latest · immich-ml:latest · redis:latest · immich-postgres:latest — data in /containers/immich/library, /containers/immich/postgres

1. Save as .env and fill in what is empty:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
# Immich for FreeBSD (Daemonless)
# Compatible with official Immich environment variables
# Docs: https://docs.immich.app/install/environment-variables

# Image tag for the Immich server and machine-learning containers.
# Defaults to 'latest' (stable). Set to 'beta' to run the Immich 3.0 pre-release.
# IMMICH_TAG=latest

# Image tag for machine learning (defaults to 'latest').

# The location where your uploaded files are stored
UPLOAD_LOCATION=/containers/immich/library

# The location where your database files are stored
DB_DATA_LOCATION=/containers/immich/postgres

# To set a timezone, uncomment the next line and change Etc/UTC to a TZ identifier
# https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List
TZ=UTC

# Connection secret for postgres. Change this to a random password!
# Use only characters A-Za-z0-9 (no special characters or spaces)
DB_PASSWORD=postgres

# Where the server looks for the other three services. The defaults are right
# when they all share one network stack, which is what this file sets up. Set
# them when postgres, redis and the ML service are somewhere else -- on their
# own private segment, or a redis you already run.
# DB_HOSTNAME=localhost
# REDIS_HOSTNAME=localhost
# IMMICH_ML_HOST=localhost
# Where the public proxy (the Public sharing choice) finds the server.
# IMMICH_SERVER_HOST=localhost

# Machine learning: false turns it off (the Machine learning choice does this).
# IMMICH_ML_ENABLED=true

# Public sharing (the Public sharing choice): the address the proxy is reached at.
# PUBLIC_BASE_URL=

# The address the server binds. Immich binds loopback unless told otherwise,
# which answers nothing if the container has an address of its own.
# IMMICH_HOST=0.0.0.0

# The values below this line do not need to be changed
###################################################################################
DB_USERNAME=postgres
DB_DATABASE_NAME=immich

2. Save as compose.yaml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
#
# Immich for FreeBSD (Daemonless)
#
# Drop-in compatible with official Immich docker-compose.yml
#
# Prerequisites:
#   pkg install podman-suite py311-podman-compose
#
# Usage:
#   1. Copy example.env to .env and edit
#   2. Run: podman-compose up -d
#

name: immich

services:
  immich-server:
    container_name: immich_server
    image: ghcr.io/daemonless/immich-server:${IMMICH_TAG:-latest}
    network_mode: host
    volumes:
      - ${UPLOAD_LOCATION}:/data
      - /etc/localtime:/etc/localtime:ro
    environment:
      DB_HOSTNAME: ${DB_HOSTNAME:-localhost}
      REDIS_HOSTNAME: ${REDIS_HOSTNAME:-localhost}
      IMMICH_MACHINE_LEARNING_URL: http://${IMMICH_ML_HOST:-localhost}:3003
      IMMICH_MACHINE_LEARNING_ENABLED: ${IMMICH_ML_ENABLED:-true}
      # Immich binds loopback unless told otherwise, so it answers nothing on
      # the host's address -- or on a published port, which forwards to the
      # container's own and not to its loopback.
      IMMICH_HOST: ${IMMICH_HOST:-0.0.0.0}
    env_file:
      - .env
    depends_on:
      - redis
      - database
      - immich-machine-learning
    restart: always

  immich-machine-learning:
    container_name: immich_machine_learning
    image: ghcr.io/daemonless/immich-ml:${IMMICH_ML_TAG:-latest}
    network_mode: host
    environment:
      HF_HOME: /cache/huggingface
      MPLCONFIGDIR: /tmp
    volumes:
      - model-cache:/cache
    env_file:
      - .env
    restart: always

  # Public links to albums for people with no account. Only with the Public
  # sharing choice; it reaches the server at IMMICH_SERVER_HOST (localhost
  # while everything is on the host) and answers on 3000.
  redis:
    container_name: immich_redis
    image: ghcr.io/daemonless/redis:latest
    network_mode: host
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - redis-data:/config
    restart: always

  database:
    container_name: immich_postgres
    image: ghcr.io/daemonless/immich-postgres:latest
    network_mode: host
    # FreeBSD requires sysvipc for PostgreSQL shared memory
    annotations:
      org.freebsd.jail.allow.sysvipc: "true"
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_DB: ${DB_DATABASE_NAME}
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - ${DB_DATA_LOCATION}:/var/lib/postgresql/data
    restart: always

volumes:
  model-cache:
  redis-data:

Then run podman-compose up -d.

Machine learning Faces, objects and smart search. Needs 2 GB of RAM and downloads about 1 GB of models on first run.

Public sharing Share albums with people who have no account, without exposing Immich itself.

immich-server:latest · immich-ml:latest · redis:latest · immich-postgres:latest — data in /containers/immich/library, /containers/immich/postgres

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# .env

DIRECTOR_PROJECT=immich
DB_PASSWORD=postgres
DB_USERNAME=postgres
DB_DATABASE_NAME=immich
TZ=
DB_DATA_LOCATION=/containers/immich/postgres
UPLOAD_LOCATION=/containers/immich/library
CACHE_LOCATION=
REDIS_DATA_LOCATION=

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
# appjail-director.yml

options:
- alias:
- ip4_inherit:
services:
  immich-server:
    name: immich_server
    priority: 100
    options:
    - container: boot args:--pull=newer
    - from: ghcr.io/daemonless/immich-server:latest
    volumes:
    - immich-data: /data
    oci:
      environment:
      - DB_HOSTNAME: !ENV '${DB_HOSTNAME:127.0.0.1}'
      - DB_USERNAME: !ENV '${DB_USERNAME}'
      - DB_PASSWORD: !ENV '${DB_PASSWORD}'
      - REDIS_HOSTNAME: !ENV '${REDIS_HOSTNAME:127.0.0.1}'
      - IMMICH_MACHINE_LEARNING_URL: '!ENV ''http://${IMMICH_ML_HOST:127.0.0.1}:3003'''
      - IMMICH_HOST: !ENV '${IMMICH_HOST:0.0.0.0}'
      - TZ: !ENV '${TZ}'
  immich-machine-learning:
    name: immich_machine_learning
    options:
    - container: boot args:--pull=newer
    - from: ghcr.io/daemonless/immich-ml:latest
    oci:
      environment:
      - HF_HOME: /cache/huggingface
      - MPLCONFIGDIR: /tmp
      - TZ: !ENV '${TZ}'
    volumes:
    - model-cache: /cache
  redis:
    name: immich_redis
    options:
    - container: boot args:--pull=newer
    - from: ghcr.io/daemonless/redis:latest
    oci:
      environment:
      - LANG: C.UTF-8
      - TZ: !ENV '${TZ}'
    volumes:
    - redis-data: /config
  database:
    name: immich_postgres
    options:
    - container: boot args:--pull=newer
    - from: ghcr.io/daemonless/immich-postgres:latest
    - template: !ENV '${PWD}/immich-postgres-template.conf'
    oci:
      environment:
      - POSTGRES_PASSWORD: !ENV '${DB_PASSWORD}'
      - POSTGRES_USER: !ENV '${DB_USERNAME}'
      - POSTGRES_DB: !ENV '${DB_DATABASE_NAME}'
    volumes:
    - db-data: /var/lib/postgresql/data
volumes:
  immich-data:
    device: !ENV '${UPLOAD_LOCATION}'
  model-cache:
    device: !ENV '${CACHE_LOCATION}'
  redis-data:
    device: !ENV '${REDIS_DATA_LOCATION}'
  db-data:
    device: !ENV '${DB_DATA_LOCATION}'

Save the files above, then run appjail-director up.

Setup Instructions

PostgreSQL shared memory. PostgreSQL wants System V IPC, which a jail does not get by default. The compose carries the annotation (org.freebsd.jail.allow.sysvipc: "true", read by ocijail) and the director bundle ships immich-postgres-template.conf for the same reason.

Machine learning. immich-ml runs a FreeBSD-native onnxruntime on the CPU; there is no GPU acceleration on FreeBSD. Models (about 1 GB) download on first use into /cache, so the first start is slow and the rest are not.

Network. The stack shares the host's network stack, so the services find each other over localhost and only 2283 needs to reach the outside. Put the parts on networks of their own and the *_HOSTNAME variables name where each one went; fjord does that for you.

Managing it. podman-compose logs -f for every service, podman logs -f immich_server for one; podman-compose restart, podman-compose down, and podman-compose pull && podman-compose up -d to update.

Troubleshooting

ML service keeps restarting

Check memory - the ML service needs at least 2GB RAM: 

1
podman logs immich_machine_learning
If you see OOM errors, give it more memory or turn the Machine learning choice off.

Database connection errors

Ensure PostgreSQL has started and the sysvipc annotation is working: 

1
podman logs immich_postgres
The database needs a few seconds to initialize on first run.

Photos not uploading from mobile

Ensure port 2283 is accessible from your network. Check firewall rules: 

1
2
# PF firewall
pass in on egress proto tcp to port 2283

Facial recognition not working

The ML service downloads models on first use. Check if models are cached: 

1
podman exec immich_machine_learning ls -la /cache/huggingface

Interactive Configuration

Parameters

Environment Variables

Variable Default Description
DB_HOSTNAME localhost
REDIS_HOSTNAME localhost
IMMICH_MACHINE_LEARNING_URL http://${IMMICH_ML_HOST:-localhost}:3003
IMMICH_MACHINE_LEARNING_ENABLED true
IMMICH_HOST 0.0.0.0
UPLOAD_LOCATION /containers/immich/library Path to store uploaded media
DB_DATA_LOCATION /containers/immich/postgres Path to store database files
DB_PASSWORD postgres PostgreSQL database password
DB_USERNAME postgres PostgreSQL username
DB_DATABASE_NAME immich PostgreSQL database name
IMMICH_ML_TAG `` Machine learning image tag (defaults to 'latest')
IMMICH_ML_ENABLED `` false turns machine learning off (set by the choice)
PUBLIC_BASE_URL `` Address the public proxy is reached at, no trailing slash (optional; it uses the request's host otherwise)
TZ `` Timezone

Volumes

Path Description
/data Media storage (mapped to UPLOAD_LOCATION)
/etc/localtime

Implementation Details

  • Architectures: amd64
  • User: bsd (UID/GID set via PUID/PGID). Defaults to 1000:1000.
  • Base: Built on ghcr.io/daemonless/base (FreeBSD 15.1).

Need help? Join our Discord community.