메인 콘텐츠로 바로가기

Dev Containers를 이용한 개발

Dev Containers는 Docker 컨테이너를 사용하여 일관되고 재현 가능한 개발 환경을 제공합니다. Mac, Linux, Windows 또는 GitHub Codespaces를 사용하여 클라우드에서 단 한 번의 클릭으로 Immich 개발 환경을 시작할 수 있습니다.

빠르게 시작하세요!

GitHub Codespaces에서 열기

Dev Containers에 대해 더 알아보기

사전 요구 사항​

시작하기 전에 다음이 필요합니다:

  • Docker Desktop (최신 버전)
  • Visual Studio Code와 Dev Containers 확장
  • Git 리포지토리 클론 용
  • 최소 8GB의 RAM (16GB 권장)
  • 20GB의 여유 디스크 공간
대체 개발 환경

이 가이드는 VS Code에 중점을 두고 있지만 Dev Container 개발을 위한 다양한 옵션이 있습니다:

로컬 편집기:

클라우드 기반 솔루션:

  • GitHub Codespaces - GitHub와 완벽히 통합되며 뛰어난 devcontainer.json 지원
  • GitPod - 최근 Dev Container 지원을 제공하는 SaaS 플랫폼 (과거에는 gitpod.yml 사용)

셀프 호스팅 옵션:

  • Coder - 엔터프라이즈 중심, Terraform 지식 필요, 셀프 관리
  • DevPod - 클라이언트 전용 도구로 뛰어난 devcontainer.json 지원, 어떤 제공자에서도 작동 (로컬, 클라우드, 온프레미스)

Dev Container 서비스​

Dev Container 환경은 다음과 같은 서비스를 포함합니다:

서비스컨테이너 이름설명포트
서버 및 웹immich-serverAPI 서버와 웹 프론트엔드를 개발 모드로 실행2283 (API)
3000 (Web)
9230 (Workers Debug)
9231 (API Debug)
데이터베이스databasePostgreSQL 데이터베이스5432
캐시redisValkey 캐시 서버6379
머신 러닝immich-machine-learningImmich ML 모델 추론 서버3003

시작하기​

1단계: 리포지토리 클론​

git clone https://github.com/immich-app/immich.git
cd immich

2단계: 환경 변수 설정​

immich dev containers는 .env 파일이 아닌 셸 환경에서 환경 변수를 읽습니다. 이를 통해 사전 구성이 필요 없는 클라우드 환경에서 작동합니다.

구성

로컬에서 실행 중이거나 기존 DB 및/또는 사진 저장 폴더를 생성하고자 하는 경우, Dev Container를 시작하기 전에 UPLOAD_LOCATION 변수를 셸 환경에서 설정해야 합니다. 이를 통해 업로드된 파일 저장 위치와 DB 데이터 저장 위치가 결정됩니다.

# 현재 세션에만 임시로 설정
export UPLOAD_LOCATION=/opt/dev_upload_folder

# 지속성을 위해 셸 프로필에 추가
# (~/.bashrc, ~/.zshrc, ~/.bash_profile 등)
echo 'export UPLOAD_LOCATION=/opt/dev_upload_folder' >> ~/.bashrc
source ~/.bashrc

3단계: Dev Container 실행​

팁

Immich 개발은 Docker Compose 기반 개발을 위한 base images를 많이 활용합니다. 따라서 VSCode의 Clone Repository in a Container Volume 명령은 사용할 수 없습니다.

VS Code UI 사용:​

  1. 클론한 리포지토리를 VS Code에서 엽니다
  2. F1 또는 Ctrl/Cmd+Shift+P를 눌러 명령 팔레트를 엽니다
  3. 'Dev Containers: Rebuild and Reopen in Container' 입력 후 선택
  4. 목록에서 'Immich - Backend, Frontend and ML' 선택
  5. 컨테이너가 빌드 및 시작되길 기다립니다 (첫 실행 시 몇 분 정도 소요될 수 있음)

VS Code 빠른 동작 사용:​

  1. 리포지토리를 VS Code에서 엽니다
  2. 컨테이너에서 다시 열지 묻는 팝업이 표시됩니다
  3. '컨테이너에서 다시 열기' 클릭

명령줄 사용:​

# DevContainer CLI 사용
devcontainer up --workspace-folder .

환경 변수 세부 정보​

Dev Containers가 환경 변수를 처리하는 방법​

.env 파일을 사용하는 Docker Compose 기반 Immich 개발 설정과 다르게 Immich Dev Containers는 .devcontainer/devcontainer.json에 구성된 대로 셸 환경에서 환경 변수를 읽습니다:

"remoteEnv": {
    "UPLOAD_LOCATION": "${localEnv:UPLOAD_LOCATION:./Library}",
    "DB_PASSWORD": "${localEnv:DB_PASSWORD:postgres}",
    "DB_USERNAME": "${localEnv:DB_USERNAME:postgres}",
    "DB_DATABASE_NAME": "${localEnv:DB_DATABASE_NAME:immich}"
}

${localEnv:VARIABLE:default} 구문은 선택적으로 기본값과 함께 셸 환경에서 읽습니다.

업로드 위치 경로 해석​

UPLOAD_LOCATION 환경 변수는 파일 저장 위치를 제어합니다:

기본값: ./Library (docker 디렉토리를 기준으로 상대 경로) 해결된 경로: <immich-root>/docker/Library

바인드 마운트 생성:

# .devcontainer/server/container-compose-overrides.yml에서
- ${UPLOAD_LOCATION-./Library}/photos:/workspaces/immich/server/upload
- ${UPLOAD_LOCATION-./Library}/postgres:/var/lib/postgresql/data

데이터베이스 구성​

이 변수들은 (개발 기준으로) 적절한 기본값을 가지지만 사용자 정의가 가능합니다:

변수기본값설명
DB_PASSWORDpostgresPostgreSQL 비밀번호
DB_USERNAMEpostgresPostgreSQL 사용자 이름
DB_DATABASE_NAMEimmich데이터베이스 이름

환경 변수 설정​

다음 명령을 셸 프로필 (~/.bashrc, ~/.zshrc, ~/.bash_profile, 등)에 추가하세요:

# 필수 항목
export UPLOAD_LOCATION=./Library  # 또는 절대 경로

# 선택 항목 (기본값이 아닌 값을 사용하는 경우에만 필요)
export DB_PASSWORD=your_password
export DB_USERNAME=your_username
export DB_DATABASE_NAME=your_database

셸 구성을 다시 로드하세요:

source ~/.bashrc  # 또는 ~/.zshrc 등

Git 구성​

SSH 키 및 인증​

Dev Container 내부에서 GitHub 액세스를 위해 SSH 키를 사용하려면:

  1. 호스트 머신에서 SSH 에이전트를 시작하십시오:

    eval "$(ssh-agent -s)"
    ssh-add ~/.ssh/id_rsa  # 또는 키 경로

  2. VS Code는 SSH 에이전트를 컨테이너로 자동 포워딩합니다

자세한 내용은 Git 자격 증명 공유에 대한 VS Code 가이드를 참조하세요.

커밋 서명​

커밋 서명을 위해 SSH 키를 사용하려면 GitHub의 SSH 커밋 서명 가이드를 참조하세요.

개발 워크플로​

자동 설정​

Dev Container가 시작되면 자동으로:

  1. post-create 스크립트를 실행합니다 (container-server-post-create.sh):

    • node 사용자에 대한 파일 권한을 조정
    • 의존성 설치: 모든 패키지에서 npm install 실행
    • TypeScript SDK 빌드: open-api/typescript-sdk에서 npm run build 실행

  2. VS Code 태스크를 통해 개발 서버 시작:

    • Immich API Server (Nest) - 파일 변경 시 핫 로딩 로깅과 함께 API 서버 시작 (포트 2283)
    • Immich Web Server (Vite) - 파일 변경 시 핫 로딩과 함께 웹 프론트엔드 실행 (포트 3000)
    • 두 서버는 파일 변경을 감지하여 자동으로 재 컴파일

  3. 포트 포워딩 구성:

정보

Dev Container 설정은 전통적인 설정의 make dev 명령을 대체합니다. 모든 서비스는 컨테이너를 열 때 자동으로 시작됩니다.

서비스 접근​

실행 후 다음에 접근 가능합니다:

서비스URL설명
웹 UIhttp://localhost:3000메인 웹 인터페이스
APIhttp://localhost:2283REST API 엔드포인트 (직접 사용하지 않으며 웹 UI가 http://localhost:3000/api를 통해 노출)
데이터베이스localhost:5432PostgreSQL (사용자 이름: postgres) (직접 사용하지 않음)

모바일 앱 연결​

Dev Container에 모바일 앱을 연결하려면:

  1. 기계의 IP 주소를 확인합니다
  2. 모바일 앱에서: http://YOUR_IP:3000/api를 사용합니다
  3. 방화벽이 포트 2283의 연결을 허용하도록 설정합니다

코드 변경​

  • 서버 코드 (/server): 변경 사항이 자동으로 재시작을 트리거
  • 웹 코드 (/web): 변경 사항이 핫 모듈 교체를 트리거
  • 데이터베이스 마이그레이션: 서버 디렉터리에서 npm run sync:sql 실행
  • API 변경: make open-api로 TypeScript SDK 재생성

테스트​

테스트 실행​

Dev 컨테이너는 여러 방식의 테스트 실행을 지원합니다:

Make 명령어 사용 (권장)​

# 특정 구성 요소에 대한 테스트 실행
make test-server         # 서버 유닛 테스트
make test-web           # 웹 유닛 테스트
make test-e2e           # 엔드 투 엔드 테스트
make test-cli           # CLI 테스트

# 모든 테스트 실행
make test-all           # 모든 구성 요소 테스트 실행

# 통합 테스트 (중간 테스트)
make test-medium-dev    # 엔드 투 엔드 테스트

NPM 직접 사용​

# 서버 테스트
cd /workspaces/immich/server
npm test                # 모든 테스트 실행
npm run test:watch     # 실시간 감시 모드
npm run test:cov       # 테스트 커버리지 보고서

# 웹 테스트
cd /workspaces/immich/web
npm test               # 모든 테스트 실행
npm run test:watch     # 실시간 감시 모드

# 엔드 투 엔드 테스트
cd /workspaces/immich/e2e
npm run test           # API 테스트 실행
npm run test:web       # 웹 UI 테스트 실행

코드 품질 명령어​

# 린팅
make lint-server        # 서버 코드 린팅
make lint-web          # 웹 코드 린팅
make lint-all          # 모든 구성 요소 린팅

# 코드 포맷
make format-server      # 서버 코드 포맷
make format-web        # 웹 코드 포맷
make format-all        # 모든 코드 포맷

# 타입 체크
make check-server       # 서버 타입 체크
make check-web         # 웹 타입 체크
make check-all         # 모든 구성 요소 체크

# 전체 위생 체크
make hygiene-all       # 린팅, 포맷, 체크, SQL 동기화 및 감사 실행

추가적인 Make 명령어​

# 빌드 명령어
make build-server       # 서버 빌드
make build-web         # 웹 앱 빌드
make build-all         # 모두 빌드

# API 생성
make open-api          # OpenAPI 사양 생성
make open-api-typescript # TypeScript SDK 생성
make open-api-dart     # Dart SDK 생성

# 데이터베이스
make sql               # 데이터베이스 스키마 동기화

# 종속성
make install-server    # 서버 종속성 설치
make install-web      # 웹 종속성 설치
make install-all      # 모든 종속성 설치

디버깅​

Dev 컨테이너는 디버깅을 위한 사전 설정이 완료되어 있습니다:

  1. API 서버 디버깅:

    • VS Code에서 브레이크포인트 설정
    • F5를 누르거나 "Run and Debug" 패널 사용
    • "Attach to Server" 구성 선택
    • 디버그 포트: 9231

  2. 워커 디버깅:

    • "Attach to Workers" 구성 사용
    • 디버그 포트: 9230

  3. 웹 디버깅:

    • 브라우저 개발자 도구 사용
    • VS Code 디버거로 Chrome/Edge 확장 지원

문제 해결​

일반적인 문제​

권한 오류​

문제: EACCES 또는 권한 거부 오류
솔루션:

  • Dev 컨테이너는 node 사용자 (UID 1000)로 실행됩니다
  • 호스트 UID가 다를 경우 권한 문제를 볼 수 있습니다
  • 컨테이너를 재구축해 보세요: "Dev Containers: Rebuild Container"

컨테이너 시작 안됨​

문제: Dev 컨테이너가 시작 또는 빌드 실패
솔루션:

  1. Docker 실행 여부 확인: docker ps
  2. Docker 리소스 정리: docker system prune -a
  3. 디스크 공간 확인
  4. Docker Desktop 리소스 제한 검토

포트 이미 사용 중​

문제: "포트 3000/2283이 이미 사용 중"
솔루션:

  1. 충돌하는 서비스 확인: lsof -i :3000 (macOS/Linux)
  2. 충돌하는 서비스 중지 또는 포트 매핑 변경
  3. Docker Desktop 재시작

업로드 위치 미설정​

문제: UPLOAD_LOCATION 누락 에러 솔루션:

  1. 환경 변수 설정: export UPLOAD_LOCATION=./Library
  2. 쉘 프로필에 추가해 지속성 유지
  3. 터미널과 VS Code를 재시작

데이터베이스 연결 실패​

문제: PostgreSQL 연결 실패
솔루션:

  1. 모든 컨테이너 실행 여부 확인: docker ps
  2. 로그 확인: "Dev Containers: Show Container Log"
  3. 데이터베이스 자격 증명이 환경 변수와 일치하는지 확인

도움 받기​

문제가 발생하면:

  1. 컨테이너 로그 확인: 보기 → 출력 → "Dev Containers" 선택
  2. 캐시 없이 재구축: "Dev Containers: Rebuild Container Without Cache"
  3. 일반 Docker 문제 검토
  4. Discord의 #help-desk-support 채널에서 문의

모바일 개발​

Dev 컨테이너는 서버 및 웹 개발에 초점을 맞추고 있지만, 테스트를 위한 모바일 앱 연결이 가능합니다:

iOS/Android 앱 연결​

  1. API가 접근 가능한지 확인:

    # 머신의 IP 찾기
    # macOS
    ipconfig getifaddr en0
    # Linux
    hostname -I
    # Windows (WSL2에서)
    ip addr show eth0

  2. 모바일 앱 구성:

    • 서버 URL: http://YOUR_IP:2283/api
    • 방화벽이 포트 2283을 허용하는지 확인

  3. 모바일 전체 개발에 대한 자세한 내용은 모바일 개발 가이드를 참조하세요. 여기에는 다음이 포함됩니다:

    • Flutter 설정
    • 시뮬레이터/디바이스에서 실행
    • 모바일 특화 디버깅

고급 설정​

사용자 정의 VS Code 확장​

.devcontainer/devcontainer.json에 확장을 추가하세요:

"customizations": {
  "vscode": {
    "extensions": [
      "your.extension-id"
    ]
  }
}

추가적인 서비스​

서비스 추가(e.g., Redis Commander)하려면 수정하세요:

  1. /docker/docker-compose.dev.yml - 서비스 정의 추가
  2. /.devcontainer/server/container-compose-overrides.yml - 필요 시 오버라이드 추가

리소스 제한​

Docker Desktop 리소스를 조정하세요:

  • macOS/Windows: Docker Desktop → Settings → Resources
  • Linux: Docker 데몬 구성 수정

권장 최소 사양:

  • CPU: 4코어
  • 메모리: 8GB
  • 디스크: 20GB

앞으로의 단계​

이 페이지 편집
마지막 업데이트 에 업데이트됨 vscodeuser@aigc에 의해 업데이트됨