- 2024년 10월 30일 변경 내용 : TrueNAS가 24.10업데이트 대응 docker compose 설치방법 추가
- 2025년 1월 22일 변경 내용 : 쿠버네티스 설치 내용 분리, 일반 docker compose내용 추가
- 2025년 2월 17일 변경 내용 : immich-go 최신 버전의 cli 명령 수정
개요
사진과 비디오를 동기화하여 로컬에 저장하고, 웹 앱을 통해 갤러리처럼 볼 수 있는 사진 관리 툴의 대표주자는 시놀로지의 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구문을 볼 수 있게 됩니다.
이 중 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
아래처럼 immich가 설치된 것을 확인할 수 있고,
2283포트로 접속하면 아래처럼 Immich가 정상적으로 구동된 것을 확인할 수 있습니다.
공식 카탈로그로 설치하기
Dataset 준비하기
TrueNAS 공식 카탈로그의 Immich는 총 7 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 Configuration
Machine Learning Image Type에서 아래와 같이 3가지의 방식을 확인할 수 있습니다.
- Default : 순수 CPU퍼포먼스
- Cuda : NVIDIA GPU활용
- Openvino : 딥러닝 모델 최적화를 위해 인텔에서 개발한 Toolkit(이라고 합니다)
또한, DB 패스워드와 Redis 패스워드를 각각 입력해 줍니다.
Storage Configuration
스토리지를 구성하는 단계입니다. 위에서 생성한 dataset을 Host Path로 하나씩 매핑해주면 됩니다.
설정 후 간단하게 테스트하며 사용해 보신 후 dataset구성을 변경할 필요가 있는지 체크해 보시는게 좋습니다.
서로 다른 pool에 생성된 dataset은 쉽게 이동할 수 없기 때문에, 몇백 기가바이트의 데이터가 쌓인 후엔 일이 커지기 때문입니다.
- Library, Thumbs, Profile



- DB와 사진, 비디오



Resources Configuration
머신 러닝을 Default로 설정하고 CPU를 너무 많이 설정했을 경우, 얼굴 인식 등에 과도하게 자원이 사용되면서 호스트까지 영향을 미칠 수 있습니다. 적절하게 자원을 설정해 줄 필요가 있는 부분입니다.
이제 Install을 클릭해 설치를 시작합니다. 초기 Deploy에 시간이 꽤 필요합니다.
Immich 실사용하기
초기 설정
TrueNAS에서는 Web Portal을, 쿠버네티스에서 설치했다면 설정한 경로를 통해 초기 설정을 시작할 수 있습니다.
관리자 계정으로 사용할 이메일주소와 비밀번호, 표기될 이름을 설정하고 로그인합니다.
다크모드를 사용할 것인지 묻는 질문을 넘기고 나면, 아래처럼 파일명 전환 규칙을 설정할 것인지를 물어봅니다.
시놀로지 포토를 사용했다면 익숙한 옵션입니다.
아래 스크린샷대로라면 개별 유저의 폴더 아래에
- 년도별로 폴더를 만들고
- 년도 폴더 아래에 다시 년-일-월 형식으로 폴더를 만들고
- 그 폴더에 기존 파일이름을 인용합니다.
폴더가 너무 많이 생성되겠죠..
저는 대충 아래같이 설정했습니다. 년도별로만 폴더가 생성되고 파일이름은 IMG_년월일_시분초입니다.
설정이 완료된 후, 임시로 몇 가지 바탕화면용 사진을 업로드해보면, 바로바로 표시되는 것을 확인할 수 있고, SMB Share를 통해 사진 저장 폴더를 확인해보면 지정한 규칙대로 파일명이 잘 변경된 것을 확인하실 수 있습니다.
OAuth 설정
Immich는 OAuth를 통한 SSO를 지원합니다. Administration – Settings – Authentication Settings – OAuth를 통해 해당 메뉴에 진입할 수 있습니다.
해당 기능은 Authentik, Authelia 등을 이용해 설정할 수 있고, 방법은 이미 설명해 놓은 글을 참고해 주시면 감사하겠습니다.
해당 기능을 통해 자동가입되는 유저의 스토리지 용량 제한 기능도 설정할 수 있습니다.
모바일 사진 동기화
Immch 앱을 이용해 Synology Photo와 동일한 요령으로 사진을 동기화할 수 있습니다.
해당 부분에 대한 설명은 생략하겠습니다.
Synology Photo 마이그레이션
Immich에서 Account Settings – API Keys를 통해 API Key를 발급받습니다.
해당 키를 메모장에 잘 복사해 둔 뒤, Immich-go를 다운로드 받습니다. 윈도우, 리눅스는 물론 맥과 FreeBSD용 클라이언트까지 지원합니다.
윈도우용을 다운받아 적당한 곳에 압축해제한 뒤 터미널로 접근합니다.
터미널이 열리면 아래와 같이 입력합니다.
./immich-go upload from-folder -server=http://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 http://10.10.10.10:3001 -k W1HVe223JA85zRPMgTJCde59VRJSA1pWHuHuvCg --skip-verify-ssl \\10.10.10.13\homes\fenta\Photos
네트워크 경로 대신 압축된 파일도 지원하는데, 내용물의 일부가 누락되거나 일정 파일 개수가 넘어가면 멈추는 등의 이슈가 있으므로, 압축을 해제해서 진행하는 것을 추천드립니다.
실수 없이 제대로 입력했다면 아래처럼 사진 업로드가 진행되는 것을 확인할 수 있습니다.
업로드 되는 사진은 실시간으로 웹 UI에서 확인할 수 있습니다.
앨범을 지정하고 싶다면 --into-album “string”을 추가하면, 사진 업로드가 끝난 후 일괄적으로 앨범에 추가해 줍니다.
./immich-go upload from-folder -s http://10.10.10.10:3001 -k W1HVe223JA85zRPMgTJCde59VRJSA1pWHuHuvCg --skip-verify-ssl --into-album "test" \\10.10.10.13\homes\fenta\Photos\wedding
시간이 지남에 따라 썸네일 생성이 완료되고, 머신 러닝으로 인식한 ‘얼굴 인식 결과’도 확인할 수 있습니다.
뿐만 아니라, 단어를 검색하면 연관된 결과를 띄워주기도 합니다.
(틀린 것도 있지만, 대체로 일치하는 것을 보여줍니다.)
만일, Migration이 아닌, 시놀로지 포토와 병행해서 사용하길 원한다면 External Library를 설정하는 것을 추천합니다.
마무리
Immich에서 엄청난 Breaking changes가 나오면서 셋팅을 다시 해야 하는 빈도가 많이 줄었고(=안정화되었고) 기능과 성능이 충분히 정품 시놀로지에 비해 만족스럽다고 느끼고 있습니다.
그렇기 때문에, 시놀로지 포토를 고집할 필요가 없어지면서 정품 시놀로지에 대한 욕망이 한차례 더 줄어드는 결과가 되었네요 ㅎ_ㅎ
관련 글
2025.01.23 - [Kubernetes] - 쿠버네티스(K8S) 환경에서 Immich 설치하기
쿠버네티스(K8S) 환경에서 Immich 설치하기
개요홈서버에서 쿠버네티스를 운용하는 건 흔치 않지만, 마침 제가 실험적으로 운용하고 있어서 포스팅합니다.환경은 Proxmox에 마스터 노드 3대, 워커 노드 3대의 Rocky Linux로 이루어진 클러스터
worklazy.net
2025.01.23 - [Apps] - Authentik으로 홈서버 SSO 구현하기 (3) – OAuth/OpenID
Authentik으로 홈서버 SSO 구현하기 (3) – OAuth/OpenID
개요LDAP는 있으면 좋지만, 이것만으로는 번거로운 로그인 과정을 전부 해결할 수는 없습니다.이번 글에서는 OAuth / OpenID Provider를 설정하는 방법을 적어 보겠습니다.LDAP가 조직 내부 네트워크 인
worklazy.net
출처
1. https://immich.app/docs/install/docker-compose/
Docker Compose [Recommended] | Immich
Docker Compose is the recommended method to run Immich in production. Below are the steps to deploy Immich with Docker Compose.
immich.app