Immich Server Setup Guide

Step 1: Update Your System

Ensure that your system is fully updated before beginning the installation:

sudo apt-get update && sudo apt-get upgrade

Step 2: Install CIFS Utilities and Samba

You’ll need cifs-utils for mounting network shares and samba to manage credentials:

sudo apt-get install cifs-utils samba

Step 3: Set Up Samba Credentials

Create a credentials file to securely store your NAS credentials:

sudo nano /etc/samba/credentials

Add the following to the file:

username=your_username
password=your_password

Set secure permissions for the credentials file:

sudo chmod 600 /etc/samba/credentials

Step 4: Create Mount Points and Mount NAS Shares

Create directories to mount your NAS shares:

sudo mkdir -p /mnt/nas/share1 /mnt/nas/share2 /mnt/nas/immich

Mount the shares using the credentials file:

sudo mount -t cifs //192.168.1.100/share1 /mnt/nas/share1 -o credentials=/etc/samba/credentials,iocharset=utf8
sudo mount -t cifs //192.168.1.100/share2 /mnt/nas/share2 -o credentials=/etc/samba/credentials,iocharset=utf8
sudo mount -t cifs //192.168.1.100/immich /mnt/nas/immich -o credentials=/etc/samba/credentials,iocharset=utf8

Step 5: Automate NAS Mounting via fstab

To make sure the NAS shares mount automatically at boot, edit the /etc/fstab file:

sudo nano /etc/fstab

Add the following lines:

//192.168.1.100/share1 /mnt/nas/share1 cifs credentials=/etc/samba/credentials,iocharset=utf8 0 0
//192.168.1.100/share2 /mnt/nas/share2 cifs credentials=/etc/samba/credentials,iocharset=utf8 0 0
//192.168.1.100/immich /mnt/nas/immich cifs credentials=/etc/samba/credentials,iocharset=utf8 0 0

Apply the configuration:

sudo mount -a

Step 6: Install Docker and Docker Compose

Install Docker and Docker Compose:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo apt-get install docker-compose

Step 7: Install Immich

Install Immich using the provided script:

curl -o- https://raw.githubusercontent.com/immich-app/immich/main/install.sh | bash

Step 8: Configure the .env File

Update the .env file with the correct storage locations on your NAS:

nano .env

Add or modify the following environment variables to point to your NAS paths:

UPLOAD_LOCATION=/mnt/nas/immich/upload
LIBRARY_LOCATION=/mnt/nas/immich/library
THUMBS_LOCATION=/mnt/nas/immich/thumbs
VIDEO_LOCATION=/mnt/nas/immich/encoded-video
PROFILE_LOCATION=/mnt/nas/immich/profile
DB_DATA_LOCATION=/mnt/nas/immich/postgres-data

Step 9: Update the docker-compose.yml File

Edit the docker-compose.yml file to ensure the volumes point to your NAS directories:

cd immich-app/
nano docker-compose.yml

Ensure the following configuration in the docker-compose.yml file:

services:
  immich-server:
    container_name: immich_server
    image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
    volumes:
      - ${UPLOAD_LOCATION}:/usr/src/app/upload
      - ${LIBRARY_LOCATION}:/usr/src/app/upload/library
      - ${THUMBS_LOCATION}:/usr/src/app/upload/thumbs
      - ${VIDEO_LOCATION}:/usr/src/app/upload/encoded-video
      - ${PROFILE_LOCATION}:/usr/src/app/upload/profile
      - /etc/localtime:/etc/localtime:ro
      - /mnt/nas/share1:/mnt/nas/share1
      - /mnt/nas/share2:/mnt/nas/share2
      - /mnt/nas/immich:/mnt/nas/immich
    env_file:
      - .env
    ports:
      - 2283:3001
    depends_on:
      - redis
      - database
    restart: always
  redis:
    container_name: immich_redis
    image: redis:6.2-alpine
    healthcheck:
      test: redis-cli ping || exit 1
    restart: always
  database:
    container_name: immich_postgres
    image: docker.io/tensorchord/pgvecto-rs:pg14-v0.2.0
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_DB: ${DB_DATABASE_NAME}
    volumes:
      - ${DB_DATA_LOCATION}:/var/lib/postgresql/data
    restart: always

Step 10: Start Immich

Now, bring up the services:

docker-compose up -d --build

Step 11: Check for Errors and Logs

To monitor if everything is working fine, you can check the logs:

docker-compose logs -f

Troubleshooting

1. Docker Daemon Not Running

If Docker commands fail with errors like Cannot connect to the Docker daemon, check the Docker service status:

sudo systemctl status docker

If Docker isn’t running, start or restart it:

sudo systemctl start docker
sudo systemctl restart docker

2. Permission Denied Errors

If Docker can’t remove or stop containers, you might need to forcefully remove them:

sudo docker rm -f <container_id>

3. File Permissions on NAS

Ensure that the Postgres data directory has correct permissions:

sudo chown -R 999:999 /mnt/nas/immich/postgres-data
sudo chmod -R 700 /mnt/nas/immich/postgres-data

4. Force Docker Clean-Up

If containers are not starting correctly, you can clean up Docker resources:

docker system prune -f
docker volume prune -f

5. Fixing start_interval in healthcheck

If you encounter an error related to start_interval in your docker-compose.yml file, replace start_interval with start_period in the healthcheck section of the database service:

healthcheck:
  test: pg_isready --dbname='${DB_DATABASE_NAME}' || exit 1
  interval: 5m
  timeout: 10s
  retries: 5
  start_period: 30s

6. Restart Docker and System

If nothing works, restarting Docker or the entire system can clear locked resources:

sudo systemctl restart docker
sudo reboot