Dev Containersを使用した開発

Dev ContainersはDockerコンテナを使用して、一貫性と再現性のある開発環境を提供します。ワンクリックで、Mac、Linux、Windows、またはGitHub Codespacesを使用したクラウド上でのImmich開発環境を開始できます。

すぐに始めましょう！

Dev Containersについて詳しく学ぶ

前提条件

開始する前に、以下を確認してください：

Docker Desktop（最新バージョン）
- Mac
- Windows（WSL2バックエンド推奨）
- Linux
Visual Studio CodeとDev Containers拡張機能
リポジトリをクローンするためのGit
少なくとも8GBのRAM（16GB推奨）
20GBの空きディスク容量

代替の開発環境

このガイドはVS Codeに焦点を当てていますが、Dev Containersで開発するための選択肢はたくさんあります：

ローカルエディタ:

IntelliJ IDEA - JetBrainsのフルIDEサポート
neovim - 軽量なターミナルベースのエディタ
Emacs - 拡張可能なテキストエディタ
DevContainer CLI - コマンドラインインターフェイス

クラウドベースのソリューション:

GitHub Codespaces - GitHub完全統合、優れたdevcontainer.jsonサポート
GitPod - 最近のDev Containerサポートを備えたSaaSプラットフォーム（以前はgitpod.ymlを使用）

自己ホスティングオプション:

Coder - エンタープライズ向け、Terraformの知識が必要、自己管理型
DevPod - CLIツールで、あらゆるプロバイダー（ローカル、クラウド、オンプレミス）で動作

Dev Containerサービス

Dev Container環境は次のサービスで構成されています：

サービス	コンテナ名	説明	ポート
サーバー＆Web	`immich-server`	開発モードでAPIサーバーとWebフロントエンドを実行	2283 (API) 3000 (Web) 9230 (Workers Debug) 9231 (API Debug)
データベース	`database`	PostgreSQLデータベース	5432
キャッシュ	`redis`	Valkeyキャッシュサーバー	6379
機械学習	`immich-machine-learning`	Immich 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ベースの開発用に特殊なベース画像が広く使用されます。この理由から、VS CodeのClone Repository in a Container Volumeコマンドは使用できません。

VS Code UIを使用:

クローンしたリポジトリをVS Codeで開く
F1またはCtrl/Cmd+Shift+Pを押してコマンドパレットを開く
"Dev Containers: Rebuild and Reopen in Container"を入力して選択
リストから"Immich - Backend, Frontend and ML"を選択
コンテナがビルドおよび起動するのを待つ（初回は数分かかる場合があります）

VS Codeクイックアクションを使用:

リポジトリをVS Codeで開く
コンテナで再オープンするか尋ねるポップアップが表示される
"Reopen in Container"をクリック

コマンドラインを使用:

# 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_PASSWORD`	`postgres`	PostgreSQLパスワード
`DB_USERNAME`	`postgres`	PostgreSQLユーザー名
`DB_DATABASE_NAME`	`immich`	データベース名

環境変数を設定

これらのデータをシェルプロファイル（~/.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キーを使用するには：

ホストマシンでSSHエージェントを開始：

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_rsa  # またはキーのパス

VS CodeはSSHエージェントを自動的にコンテナに転送

詳細な手順については、Git資格情報を共有するためのVS Codeガイドをご覧ください。

コミット署名

コミット署名にSSHキーを使用するには、SSHコミット署名に関するGitHubガイドをご覧ください。

開発ワークフロー

自動セットアップ

Dev Containerが起動すると、自動的に以下が行われます：

ポストクリエイトスクリプト（container-server-post-create.sh）を実行：
- nodeユーザーにファイル権限を調整
- すべてのパッケージで依存関係をインストール：npm install
- TypeScript SDKをビルド：npm run build in open-api/typescript-sdk
VS Codeタスクを通じて開発サーバーを開始：
- Immich API Server (Nest) - ポート2283でホットリロードが有効なAPIサーバー
- Immich Web Server (Vite) - ポート3000でホットリロードが有効なWebフロントエンド
- 両サーバーはファイル変更を監視し、自動的に再コンパイル
ポートフォワーディングを設定：
- Web UI: http://localhost:3000（自動的に開かれます）
- API: http://localhost:2283
- デバッグポート: 9230 (Workers), 9231 (API)

情報

Dev Containerセットアップは従来のmake devコマンドを置き換えます。コンテナを開くと、すべてのサービスが自動的に開始されます。

サービスへのアクセス

起動中、次のサービスにアクセスできます：

サービス	URL	説明
Web UI	http://localhost:3000	メインのWebインターフェース
API	http://localhost:2283	REST APIエンドポイント（直接使用されません。Web UIはこれをhttp://localhost:3000/apiで公開）
データベース	localhost:5432	PostgreSQL（ユーザー名：`postgres`）（直接使用されません）

モバイルアプリの接続

モバイルアプリをDev Containerに接続するには：

自分のマシンのIPアドレスを確認
モバイルアプリでhttp://YOUR_IP:3000/apiを使用
ファイアウォールがポート2283への接続を許可していることを確認

コード変更を行う

サーバーコード (/server): 変更は自動再起動をトリガー
Webコード (/web): 変更はホットモジュール交換をトリガー
データベースマイグレーション: サーバーディレクトリで npm run sync:sql を実行してください
APIの変更: make open-api でTypeScript SDKを再生成してください

テスト

テストの実行

Devコンテナでは、複数の方法でテストを実行できます:

Makeコマンドを使用 (推奨)

# 特定のコンポーネントのテストを実行
make test-server         # サーバーユニットテスト
make test-web           # 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       # カバレッジレポート

# Webテスト
cd /workspaces/immich/web
npm test               # すべてのテストを実行
npm run test:watch     # ウォッチモード

# E2Eテスト
cd /workspaces/immich/e2e
npm run test           # APIテストを実行
npm run test:web       # Web UIテストを実行

コード品質コマンド

# リンティング
make lint-server        # サーバーコードをリント
make lint-web          # Webコードをリント
make lint-all          # すべてのコンポーネントをリント

# フォーマット
make format-server      # サーバーコードをフォーマット
make format-web        # Webコードをフォーマット
make format-all        # すべてのコードをフォーマット

# 型チェック
make check-server       # サーバーを型チェック
make check-web         # Webを型チェック
make check-all         # すべてのコンポーネントをチェック

# 完全な衛生チェック
make hygiene-all       # リント、フォーマット、チェック、SQL同期、監査

その他のMakeコマンド

# ビルドコマンド
make build-server       # サーバーをビルド
make build-web         # 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      # Web依存関係をインストール
make install-all      # すべての依存関係をインストール

デバッグ

Dev コンテナはデバッグ用に事前設定されています:

APIサーバーデバッグ:
- VS Codeでブレークポイントを設定
- F5 を押すか「実行とデバッグ」パネルを使用
- 「Attach to Server」構成を選択
- デバッグポート: 9231
ワーカーデバッグ:
- 「Attach to Workers」構成を使用
- デバッグポート: 9230
Webデバッグ:
- ブラウザのDevToolsを使用
- VS CodeのChrome/Edge拡張機能のデバッガー対応

トラブルシューティング

一般的な問題

権限エラー

問題: EACCES または権限拒否エラー
解決策:

Dev コンテナは nodeユーザー (UID 1000) として実行されます
ホストUIDが異なる場合、権限に問題が発生することがあります
コンテナを再構築してください: 「Dev Containers: Rebuild Container」

コンテナが起動しない

問題: Devコンテナが起動またはビルドに失敗する
解決策:

Dockerが実行中であることを確認: docker ps
Dockerリソースをクリーンアップ: docker system prune -a
空きディスク容量の確認
Docker Desktopのリソース制限を確認

ポートが既に使用中

問題: 「ポート3000/2283が既に使用されています」
解決策:

競合しているサービスを確認: lsof -i :3000 (macOS/Linux)
競合サービスを停止するかポートマッピングを変更
Docker Desktopを再起動

アップロード先が設定されていない

問題: UPLOAD_LOCATION がないというエラー
解決策:

環境変数を設定: export UPLOAD_LOCATION=./Library
持続性のためにはシェルプロファイルに追加
ターミナルとVS Codeを再起動

データベース接続に失敗

問題: PostgreSQLに接続できない
解決策:

すべてのコンテナが稼働中か確認: docker ps
ログを確認: 「Dev Containers: Show Container Log」
環境変数とデータベース資格情報の一致を確認

ヘルプを得る

問題が発生した場合:

コンテナログを確認: 表示→出力→「Dev Containers」を選択
キャッシュなしで再構築: 「Dev Containers: Rebuild Container Without Cache」
一般的なDockerの問題を確認
Discord の#help-desk-supportチャンネルで質問

モバイル開発

DevコンテナはサーバーとWeb開発に重点を置いていますが、モバイルアプリを接続してテストできます:

iOS/Androidアプリの接続

APIにアクセス可能か確認:

# マシンのIPを確認
# macOS
ipconfig getifaddr en0
# Linux
hostname -I
# Windows (WSL2で)
ip addr show eth0

モバイルアプリを設定:
- サーバーURL: http://YOUR_IP:2283/api
- ファイアウォールがポート2283を許可していることを確認
完全なモバイル開発手順は、モバイル開発ガイドを参照:
- Flutterセットアップ
- シミュレーター/デバイスでの動作
- モバイル専用のデバッグ

高度な設定

カスタムVS Code拡張機能

.devcontainer/devcontainer.jsonに拡張機能を追加:

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

追加のサービス

サービスを追加 (例: Redis Commander):

/docker/docker-compose.dev.yml - サービス定義を追加
/.devcontainer/server/container-compose-overrides.yml - 必要があればオーバーライドを追加

リソース制限

Docker Desktopのリソースを調整:

macOS/Windows: Docker Desktop → 設定 → リソース
Linux: Dockerデーモン設定を変更

推奨される最低要件:

CPU: 4コア
メモリ: 8GB
ディスク: 20GB

次のステップ

アーキテクチャの概要を読む
データベース移行について学ぶ
APIドキュメントを探る
Discord の#immichに参加

前提条件​

Dev Containerサービス​

始め方​

ステップ1: リポジトリをクローン​

ステップ2: 環境変数を設定​

ステップ3: Dev Containerを起動​

VS Code UIを使用:​

VS Codeクイックアクションを使用:​

コマンドラインを使用:​

環境変数の詳細​

Dev Containersによる環境変数の管理​

アップロード場所のパス解決​

データベース設定​

環境変数を設定​

Gitの設定​

SSHキーと認証​

コミット署名​

開発ワークフロー​

自動セットアップ​

サービスへのアクセス​

モバイルアプリの接続​

コード変更を行う​

テスト​

テストの実行​

Makeコマンドを使用 (推奨)​

NPMを直接使用​

コード品質コマンド​

その他のMakeコマンド​

デバッグ​

トラブルシューティング​

一般的な問題​

権限エラー​

コンテナが起動しない​

ポートが既に使用中​

アップロード先が設定されていない​

データベース接続に失敗​

ヘルプを得る​

モバイル開発​

iOS/Androidアプリの接続​

高度な設定​

カスタムVS Code拡張機能​

追加のサービス​

リソース制限​

次のステップ​