• 2024년 10월 30일 변경 내용 : TrueNAS가 24.10업데이트 대응 docker compose 설치방법 추가
  • 2025년 1월 22일 변경 내용 : 쿠버네티스 설치 내용 분리, 일반 docker compose내용 추가
  • 2025년 2월 17일 변경 내용 : immich-go 최신 버전의 cli 명령 수정
  • 2025년 12월 2일 변경 내용 : includes: 하위에 services: {} 반영(TrueNAS업데이트)

개요

사진과 비디오를 동기화하여 로컬에 저장하고, 웹 앱을 통해 갤러리처럼 볼 수 있는 사진 관리 툴의 대표주자는 시놀로지의 Photo Station(現 Photos)입니다.

안드로이드와 아이폰 모두 전용 앱을 갖추고 있어 접근성이 좋고, 컴퓨터를 아주 못 다루지 않는 이상 메뉴얼을 참조해서 셋팅할 수 있을 정도로 설정이 쉽기 때문입니다.

구글포토가 무제한 백업 종료를 선언한 이후, 시놀로지 포토 하나 때문에 헤놀로지를 구축하고 싶어하는 분들도 여럿 보였을 정도죠.

Immich는 시놀로지 포토처럼 셀프 호스팅으로 구축할 수 있는 사진 관리툴로써, 사진을 동기화받고 갤러리처럼 볼 수 있는 앱입니다. 같은 기능을 제공하는 Photoprism이나 Immich 모두 초창기의 것들은 버그도 많고 사용하기 난해한 편이라는 의견이 많았지만, 많은 피드백을 거쳐 현재의 버전에 와서는 상당히 좋아진 것으로 평가받고 있습니다.

Photoprism은 자체 앱 없이 Nextcloud앱을 이용하고, 유료 부분에 대한 반발이 심한 것으로 보여 Immich를 설치해보겠습니다.

docker compose와 TrueNAS 환경에서 두 가지로 설치해보겠습니다.

Docker compose로 설치하기

먼저 공식 홈페이지에서 docker compose를 다운받습니다.

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

동일한 폴더에 .env파일을 생성하고 아래 내용을 참조하여 내용을 채워줍니다.

  • UPLOAD_LOCATION = Immich에 업로드한 사진, 비디오 등이 업로드 될 위치
  • DB_DATA_LOCATION = Immich에 사용될 DB데이터 저장 경로
  • IMMICH_VERSION = release(고정 추천)
  • DB_PASSWORD = DB 비밀번호
  • DB_USERNAME = DB 사용자명
  • DB_DATABASE_NAME = DB 이름
UPLOAD_LOCATION=/docker/immich/photos
DB_DATA_LOCATION=/docker/immich/db
IMMICH_VERSION=release
DB_PASSWORD=immich
DB_USERNAME=immich
DB_DATABASE_NAME=immich

작업이 완료되면 docker compose up -d를 통해 컨테이너를 띄우고 IP:2283으로 접속해 초기 설정을 진행할 수 있게 됩니다.

TrueNAS에 설치하기

Docker compose를 통해 설치하기

TrueNAS가 24.10버전으로 업데이트 되며 Custom App기능을 통해 docker-compose를 실행할 수 있게 되었습니다.

Immich 공식 docker compose를 제공하므로 쉘에서 먼저 docker compose파일을 다운받겠습니다.

truenas_admin@truenas[/mnt/dockertest/docker/compose/immich]$ wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml

그러면, 아래와 같은 긴 YAML구문을 볼 수 있게 됩니다.

Immich 사진 저장을 위한 TrueNAS 공유 폴더 생성 및 권한 설정 화면

이 중 env값으로 지정된 것은 총 6개로, 각각 UPLOAD_LOCATION, DB_DATA_LOCATION, IMMICH_VERSION, DB_PASSWORD, DB_USERNAME, DB_DATABASE_NAME입니다.

Immich는 코드 수정 및 업데이트 배포가 굉장히 활발하게 이루어지고 있는 앱이고, 이에 따라 microservice로 구성되었던 컨테이너가 본 컨테이너에 합쳐지거나, docker compose구문이 변하는 등 변화가 굉장히 큽니다. 따라서 해당 env값을 YAML 내부에 고정으로 수정하는 것은 추천하지 않습니다.

따라서, 해당 6개의 값을 env로 작성한 뒤 compose에서 참조하도록 하는 것이 좋습니다. 저는 쉘에서 immich.env라는 파일을 생성해서 env값을 기입하겠습니다.

truenas_admin@truenas[/mnt/dockertest/docker/compose/immich]$ sudo nano .env

아래에 맞춰 입력합니다.

  • UPLOAD_LOCATION = Immich에 업로드한 사진, 비디오 등이 업로드 될 위치(TrueNAS에서 Dataset 별도 준비 필요)
  • DB_DATA_LOCATION = Immich에 사용될 DB데이터 저장 경로(TrueNAS에서 Dataset 별도 준비 필요)
  • IMMICH_VERSION = release(고정 추천)
  • DB_PASSWORD = DB 비밀번호
  • DB_USERNAME = DB 사용자명
  • DB_DATABASE_NAME = DB 이름

아래는 예시값입니다.

UPLOAD_LOCATION=/mnt/dockertest/docker/immich/uploads
DB_DATA_LOCATION=/mnt/dockertest/docker/immich/db
IMMICH_VERSION=release
DB_PASSWORD=immich
DB_USERNAME=immich
DB_DATABASE_NAME=immich

여기까지 진행했다면, /mnt/dockertest/docker/compose/immich 경로에 .env과 docker-compose.yml 두 개의 파일이 존재하게 됩니다.

TrueNAS WEB UI에 돌아와서 Name은 immich, Custom Config는 아래처럼 입력하고 Save를 클릭합니다.

include:
  - /mnt/dockertest/docker/compose/immich/docker-compose.yml
services: {}
TrueNAS Apps 카탈로그에서 Immich 애플리케이션을 검색하여 설치하는 화면

아래처럼 immich가 설치된 것을 확인할 수 있고,

Immich 설치 시 데이터베이스 저장을 위한 Storage 매핑 설정 화면

2283포트로 접속하면 아래처럼 Immich가 정상적으로 구동된 것을 확인할 수 있습니다.

생성해 둔 공유 폴더를 Immich Library Storage로 매핑하는 화면

공식 카탈로그로 설치하기

Dataset 준비하기

TrueNAS 공식 카탈로그의 Immich는 총 6개의 스토리지를 요구합니다.

Upload, Library, Thumbs, Profile, Video, Postgres(DB), Postgres Backup 이렇게 총 7가지입니다.

사진과 비디오를 제외한 데이터는 SSD에 저장해 퍼포먼스를 높이고 사진과 비디오는 용량이 넉넉한 하드디스크에 저장하기 위해 아래처럼 dataset을 구성했습니다.

  • SSD : Upload, Thumbs, Profile, DB, DBbackup
  • HDD : Library, Video

dataset에 apps계정 권한을 설정해 주어야 합니다.

TrueNAS의 버전이 24로 판올림 된 후로, dataset 생성과 동시에 SMB share도 생성할 수 있으니, 같이 설정해주면 네트워크 공유로 사진 파일에 접근하기 좋습니다.

설치 완료 후 배포된 Immich 서비스의 포트 정보와 동작 상태를 확인하는 화면

사진과 비디오 파일을 저장할 라이브러리는 아래와 같이 생성했습니다.

Immich 서버 접속 후 최초 관리자 계정 가입 정보를 입력하는 화면

Immich 설치하기

Immich Configuration

Machine Learning Image Type에서 아래와 같이 3가지의 방식을 확인할 수 있습니다.

  • Default : 순수 CPU퍼포먼스
  • Cuda : NVIDIA GPU활용
  • Openvino : 딥러닝 모델 최적화를 위해 인텔에서 개발한 Toolkit(이라고 합니다)
관리자 계정 가입 후 보여지는 Immich 웹 버전의 초기 메인 화면

또한, DB 패스워드와 Redis 패스워드를 각각 입력해 줍니다.

스마트폰에 설치된 Immich 모바일 앱의 초기 구동 화면

Storage Configuration

스토리지를 구성하는 단계입니다. 위에서 생성한 dataset을 Host Path로 하나씩 매핑해주면 됩니다.

설정 후 간단하게 테스트하며 사용해 보신 후 dataset구성을 변경할 필요가 있는지 체크해 보시는게 좋습니다.

서로 다른 pool에 생성된 dataset은 쉽게 이동할 수 없기 때문에, 몇백 기가바이트의 데이터가 쌓인 후엔 일이 커지기 때문입니다.

  • Library, Thumbs, Profile
Immich 모바일 앱에 서버 주소를 입력하여 로그인 연결을 진행하는 화면 모바일 기기의 사진 앨범에 대한 접근 권한을 묻는 팝업 화면 백업할 앨범을 선택하고 포그라운드 백업을 진행 중인 모바일 앱 화면
  • DB와 사진, 비디오
동기화 완료 후 사진들이 PC 웹 브라우저의 Immich 타임라인에 나타난 화면 Immich 설치 중 데이터베이스와 사진 및 비디오 저장 경로를 연결하는 스토리지 설정 Immich 컨테이너에 데이터베이스 및 미디어 저장소 호스트 경로를 매핑하는 설정

Resources Configuration

머신 러닝을 Default로 설정하고 CPU를 너무 많이 설정했을 경우, 얼굴 인식 등에 과도하게 자원이 사용되면서 호스트까지 영향을 미칠 수 있습니다. 적절하게 자원을 설정해 줄 필요가 있는 부분입니다.

과도한 CPU 사용을 막기 위해 Immich 컨테이너의 머신 러닝 자원 할당량을 조정하는 설정

이제 Install을 클릭해 설치를 시작합니다. 초기 Deploy에 시간이 꽤 필요합니다.

Immich 실사용하기

초기 설정

TrueNAS에서는 Web Portal을, 쿠버네티스에서 설치했다면 설정한 경로를 통해 초기 설정을 시작할 수 있습니다.

관리자 계정으로 사용할 이메일주소와 비밀번호, 표기될 이름을 설정하고 로그인합니다.

Immich 초기 접속 시 관리자용 이메일, 비밀번호, 이름을 입력하여 계정을 생성하는 단계 관리자 계정 생성 후 방금 만든 정보로 Immich 서비스에 처음 로그인하는 페이지 초기 설정 과정 중 다크모드 테마 사용 여부를 선택하는 안내

다크모드를 사용할 것인지 묻는 질문을 넘기고 나면, 아래처럼 파일명 전환 규칙을 설정할 것인지를 물어봅니다.

시놀로지 포토를 사용했다면 익숙한 옵션입니다.

아래 스크린샷대로라면 개별 유저의 폴더 아래에

  1. 년도별로 폴더를 만들고
  2. 년도 폴더 아래에 다시 년-일-월 형식으로 폴더를 만들고
  3. 그 폴더에 기존 파일이름을 인용합니다.

폴더가 너무 많이 생성되겠죠..

폴더가 지나치게 세분화되어 생성되는 기본 파일명 및 폴더 생성 규칙 템플릿

저는 대충 아래같이 설정했습니다. 년도별로만 폴더가 생성되고 파일이름은 IMG_년월일_시분초입니다.

연도별 폴더 밑에 특정 형식의 파일명으로 저장되도록 사용자 정의한 스토리지 템플릿 설정

설정이 완료된 후, 임시로 몇 가지 바탕화면용 사진을 업로드해보면, 바로바로 표시되는 것을 확인할 수 있고, SMB Share를 통해 사진 저장 폴더를 확인해보면 지정한 규칙대로 파일명이 잘 변경된 것을 확인하실 수 있습니다.

임시 사진을 업로드하여 Immich 웹 인터페이스에 사진이 정상적으로 표시되는 상태 SMB 네트워크 공유 폴더에서 사용자가 지정한 규칙대로 사진 파일명과 폴더가 생성된 파일 탐색기

OAuth 설정

Immich는 OAuth를 통한 SSO를 지원합니다. Administration – Settings – Authentication Settings – OAuth를 통해 해당 메뉴에 진입할 수 있습니다.

관리자 메뉴에서 Authentik 등의 외부 인증 수단을 연동하기 위한 OAuth 설정

해당 기능은 Authentik, Authelia 등을 이용해 설정할 수 있고, 방법은 이미 설명해 놓은 글을 참고해 주시면 감사하겠습니다.

해당 기능을 통해 자동가입되는 유저의 스토리지 용량 제한 기능도 설정할 수 있습니다.

모바일 사진 동기화

Immch 앱을 이용해 Synology Photo와 동일한 요령으로 사진을 동기화할 수 있습니다.

스마트폰에서 시놀로지 포토와 유사한 방식으로 사진 백업을 진행하는 모바일 앱 설정 Immich 모바일 앱을 통해 백업할 앨범을 선택하거나 진행 상태를 확인하는 단계 사진 동기화가 진행 중이거나 완료된 모바일 앱의 갤러리 메인

해당 부분에 대한 설명은 생략하겠습니다.

Synology Photo 마이그레이션

Immich에서 Account Settings – API Keys를 통해 API Key를 발급받습니다.

마이그레이션 툴 사용을 위해 Immich 계정 설정에서 새로운 API 키를 생성하는 단계

해당 키를 메모장에 잘 복사해 둔 뒤, Immich-go를 다운로드 받습니다. 윈도우, 리눅스는 물론 맥과 FreeBSD용 클라이언트까지 지원합니다.

깃허브 저장소에서 각 운영체제에 맞는 immich-go 마이그레이션 클라이언트를 다운로드하는 페이지

윈도우용을 다운받아 적당한 곳에 압축해제한 뒤 터미널로 접근합니다.

윈도우 환경에 다운로드 받은 immich-go 압축 파일을 해제하고 명령 프롬프트를 띄운 상태

터미널이 열리면 아래와 같이 입력합니다.

./immich-go upload from-folder -server=https://10.10.10.10:3001 -key {token} --skip-verify-ssl {대상폴더}

10.10.10.10:3001부분은 Immich의 IP와 Port번호를 사용하면 됩니다. TrueNAS로 설치했다면 30041이 됩니다.

{token}은 위에서 복사해 두었던 계정의 토큰값을, {대상폴더}는 백업하고 싶은 사진이 있는 폴더의 경로를 적어주시면 됩니다.

네트워크 경로도 지원해주기 때문에, 시놀로지의 네트워크 경로를 그대로 사용할 수도 있습니다(윈도우 상에서 네트워크 로그인을 해두어야 함).

./immich-go upload from-folder -s https://10.10.10.10:3001 -k W1HVe223JA85zRPMgTJCde59VRJSA1pWHuHuvCg --skip-verify-ssl \\10.10.10.13\homes\fenta\Photos

네트워크 경로 대신 압축된 파일도 지원하는데, 내용물의 일부가 누락되거나 일정 파일 개수가 넘어가면 멈추는 등의 이슈가 있으므로, 압축을 해제해서 진행하는 것을 추천드립니다.

실수 없이 제대로 입력했다면 아래처럼 사진 업로드가 진행되는 것을 확인할 수 있습니다.

터미널에서 immich-go 명령어를 실행하여 시놀로지 포토의 사진들이 순차적으로 업로드되는 콘솔 로그

업로드 되는 사진은 실시간으로 웹 UI에서 확인할 수 있습니다.

터미널로 업로드 중인 사진들이 Immich 웹 인터페이스에 실시간으로 반영되어 나타나는 타임라인 마이그레이션이 진행됨에 따라 Immich 타임라인에 이전 사진들이 점진적으로 채워지고 있는 상태

앨범을 지정하고 싶다면 --into-album “string”을 추가하면, 사진 업로드가 끝난 후 일괄적으로 앨범에 추가해 줍니다.

./immich-go upload from-folder -s https://10.10.10.10:3001 -k W1HVe223JA85zRPMgTJCde59VRJSA1pWHuHuvCg --skip-verify-ssl --into-album "test" \\10.10.10.13\homes\fenta\Photos\wedding
특정 옵션을 사용하여 업로드된 사진들이 자동으로 지정된 앨범에 일괄 추가된 결과
Album 예시

시간이 지남에 따라 썸네일 생성이 완료되고, 머신 러닝으로 인식한 ‘얼굴 인식 결과’도 확인할 수 있습니다.

뿐만 아니라, 단어를 검색하면 연관된 결과를 띄워주기도 합니다.
(틀린 것도 있지만, 대체로 일치하는 것을 보여줍니다.)

머신 러닝을 바탕으로 특정 단어를 검색했을 때 연관된 사진들을 찾아주는 검색 결과

만일, Migration이 아닌, 시놀로지 포토와 병행해서 사용하길 원한다면 External Library를 설정하는 것을 추천합니다.

마무리

Immich에서 엄청난 Breaking changes가 나오면서 셋팅을 다시 해야 하는 빈도가 많이 줄었고(=안정화되었고) 기능과 성능이 충분히 정품 시놀로지에 비해 만족스럽다고 느끼고 있습니다.

그렇기 때문에, 시놀로지 포토를 고집할 필요가 없어지면서 정품 시놀로지에 대한 욕망이 한차례 더 줄어드는 결과가 되었네요 ㅎ_ㅎ