Skip to content

Immich Immich

Build Status Last Commit

High performance self-hosted photo and video management solution.

Daemonless daemonless/immich
Source immich-app/immich
Website immich.app

Prerequisites

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

Customize Paths, UID & Ports

Install and manage Immich on FreeBSD with fjord:

fjord install immich

Or open the App Store in the fjord web UI and install Immich from the wizard. New to fjord? See the Install Guide.

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:

# 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). 'beta' is the same image as 'latest'.
# IMMICH_TAG=latest

# Image tag for machine learning (defaults to 'latest').
# IMMICH_ML_TAG=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

# AppJail director only (compose keeps these in named volumes): where the
# ML model cache and the redis data are stored.
CACHE_LOCATION=/containers/immich/model-cache
REDIS_DATA_LOCATION=/containers/immich/redis

# 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=Etc/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:

#
# 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

# .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=/containers/immich/model-cache
REDIS_DATA_LOCATION=/containers/immich/redis
# 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}'
# The jail PostgreSQL runs in.
#
# PostgreSQL wants SysV shared memory, which a jail does not get by default --
# without these three it fails to start with a shared memory error that reads
# like a configuration problem.
#
# ip4/ip6 are set here rather than left to the director's ip4_inherit option:
# that option is a no-op in AppJail 5.5.0, and a jail with ip4 disabled cannot
# bind, so the database comes up answering nothing.

exec.start: "/bin/sh /etc/rc"
exec.stop: "/bin/sh /etc/rc.shutdown jail"
sysvmsg: new
sysvsem: new
sysvshm: new
mount.devfs
persist
ip4: inherit
ip6: inherit

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

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

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:

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:

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:

# 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:

podman exec immich_machine_learning ls -la /cache/huggingface

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
CACHE_LOCATION /containers/immich/model-cache Path for the ML model cache (AppJail director only; compose uses a named volume)
REDIS_DATA_LOCATION /containers/immich/redis Path for the redis data (AppJail director only; compose uses a named volume)
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

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 Same image as latest. Installs already set to beta.

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.

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.