Immich란?

구글 포토와 거의 동일한 UX를 제공하는 자체 호스팅 사진 관리 서비스다. 얼굴 인식, 지도 뷰, 앨범, 공유 기능까지 있고 모바일 앱도 있어서 자동 백업이 된다. 구글 포토 유료 요금제를 쓰고 있었는데 이걸로 완전히 대체했다.

설치 과정

1. 디렉토리 생성

mkdir ~/immich && cd ~/immich

2. docker-compose.yml 및 .env 다운로드

Immich 공식에서 제공하는 파일을 그대로 받아서 쓴다.

wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env

3. .env 파일 수정

vi .env

아래 두 경로를 수정한다.

UPLOAD_LOCATION=/mnt/data/immich/photos
DB_DATA_LOCATION=/home/your-username/immich-db

DB_DATA_LOCATION을 /mnt/data(NTFS) 아래로 잡으면 안 된다. 이유는 아래 트러블슈팅에서 설명한다.

4. 실행

docker compose up -d

트러블슈팅

설치 과정에서 꽤 여러 번 막혔다. 겪은 순서대로 정리한다.

1. docker compose up -d — unknown shorthand flag 오류

unknown shorthand flag: 'd' in -d

apt install docker.io로 설치한 패키지가 구버전이라 docker compose 플러그인을 지원하지 않아서 생기는 문제다.

해결: Docker 공식 레포에서 설치한다.

sudo apt install ca-certificates curl gnupg -y
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu noble stable" | sudo tee /etc/apt/sources.list.d/docker.list
sudo apt update
sudo apt install docker-compose-plugin -y

2. Compose 파일 버전 오류

ERROR: The Compose file './docker-compose.yml' is invalid because:
'name' does not match any of the regexes: '^x-'

apt install docker-compose로 설치한 구버전(1.29.x)은 최신 Compose 파일 형식을 지원하지 않는다.

해결: 구버전 제거 후 플러그인 버전으로 교체한다.

sudo apt remove docker-compose -y
sudo apt install docker-compose-plugin -y

3. docker-compose-plugin 패키지를 찾을 수 없음

E: Unable to locate package docker-compose-plugin

Ubuntu 기본 레포에는 docker-compose-plugin이 없다.

해결: 1번 해결 방법에서 Docker 공식 레포를 먼저 추가하면 된다.

4. immich_postgres 컨테이너가 계속 재시작됨

컨테이너 상태를 확인해보면 Restarting 상태로 계속 재시작만 반복한다.

docker logs immich_postgres

FATAL:  data directory "/var/lib/postgresql/data" has wrong ownership
HINT:  The server must be started by the user that owns the data directory.

원인: DB_DATA_LOCATION을 /mnt/data(NTFS) 경로로 설정했기 때문이다. NTFS는 Linux 파일 권한 시스템을 지원하지 않아서 PostgreSQL이 요구하는 소유권을 설정할 수 없다.

해결: DB 경로를 ext4 파일시스템(Ubuntu 기본 디스크)으로 바꾼다.

docker compose down
mkdir -p ~/immich-db
vi .env

.env 수정:

DB_DATA_LOCATION=/home/your-username/immich-db

docker compose up -d

사진 원본(UPLOAD_LOCATION)은 용량이 크니까 NTFS 드라이브에 둬도 되지만, DB는 반드시 ext4에 둬야 한다.

정상 실행 확인

docker compose ps

docker compose ps 결과 - 모든 컨테이너 running 상태

모든 컨테이너가 running 또는 healthy 상태면 성공이다.

브라우저에서 http://100.109.108.36:2283 접속 후 계정을 생성하면 된다.

OCI Nginx 리버스 프록시 연결

3편에서 Filebrowser에 했던 것과 동일하게 Nginx 설정을 추가한다.

server {
    listen 80;
    server_name photo.yourdomain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name photo.yourdomain.com;

    ssl_certificate     /ssl/live/yourdomain.com/fullchain.pem;
    ssl_certificate_key /ssl/live/yourdomain.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;

    # Immich는 대용량 파일 업로드가 있으므로 크기 제한 해제
    client_max_body_size 0;

    location / {
        proxy_pass http://100.109.108.36:2283;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # 웹소켓 지원 (Immich 실시간 업로드에 필요)
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Cloudflare에서 photo.yourdomain.com DNS 추가하고 Nginx 적용하면 외부에서 접근 가능하다.

Immich 외부 접근 성공

정리

  • docker.io는 구버전이라 최신 Compose 파일을 못 읽는다. Docker 공식 레포에서 설치하자
  • PostgreSQL 데이터 디렉토리는 NTFS가 아닌 ext4에 둬야 한다
  • 사진 원본은 NTFS 외장 드라이브, DB는 OS 디스크로 분리하면 된다
  • Immich Nginx 설정 시 client_max_body_size 0과 웹소켓 설정을 빠뜨리지 말 것

다음 편에서는 Vaultwarden으로 비밀번호를 자체 호스팅하는 과정을 다룬다.