Skip to content

DOCKER_ENVIRONMENT.md

Latest commit

 

History

History
235 lines (161 loc) · 10.9 KB

DOCKER_ENVIRONMENT.md

File metadata and controls

235 lines (161 loc) · 10.9 KB

Docker環境 詳細設定ガイド

このドキュメントでは、ClaudeWorkのDocker実行環境に関する詳細設定について説明します。

目次

Docker Compose によるデプロイ

ClaudeWork自体をDocker Composeで起動する場合の注意事項です。

アーキテクチャ

Docker Composeで起動すると、ClaudeWorkはコンテナ内で動作します。ホストの /var/run/docker.sock をマウントすることで、コンテナ内からホストのDockerデーモンを操作し、サンドボックスコンテナ（Claude Code実行用）を起動します。

Host
+-- Docker Engine
|   +-- claudework (アプリコンテナ)
|   |   +-- Next.js Server
|   |   +-- SQLite DB (/data/claudework.db)
|   |   +-- Docker CLI -> /var/run/docker.sock
|   |
|   +-- claude-sandbox-xxx (サンドボックスコンテナ)
|   +-- claude-sandbox-yyy (サンドボックスコンテナ)
|
+-- /var/run/docker.sock (共有)
+-- ./data/ (バインドマウント)

docker.sock マウントについて

/var/run/docker.sock のマウントにより、ClaudeWorkコンテナはホストのDockerデーモンにアクセスできます。これはサンドボックスコンテナの起動・停止・管理に必要です。

セキュリティ上の注意:

  • docker.sockへのアクセスはホストのroot権限に相当する操作が可能です
  • 信頼できる環境でのみ使用してください
  • ブラウザからのクロスオリジンアクセス制御には ALLOWED_ORIGINS を利用できますが、ネットワークレベルのアクセス制限にはなりません
  • 外部からのアクセスを制限したい場合は、CLAUDE_WORK_TOKEN を設定し、必要に応じてリバースプロキシやファイアウォールでアクセス元を制御してください
  • コンテナは node ユーザーで実行されるため、docker-compose.yml の group_add でホストの docker グループ GID を指定する必要があります（詳細は セットアップガイド を参照）

docker.sockマウントのリスク緩和策:

  • Rootless Docker: Dockerデーモン自体を非root権限で実行し、ソケット経由の権限昇格リスクを軽減
  • Docker Socket Proxy: APIエンドポイントを制限したプロキシ経由でアクセスし、不要な操作を遮断
  • ファイアウォール / ネットワークセグメンテーション: ClaudeWorkへのアクセス元を制限

データ永続化

./data:/data ボリュームマウントにより、以下のデータがホスト側に永続化されます:

パス 内容
data/claudework.db SQLiteデータベース（プロジェクト、セッション等）
data/environments/ Docker環境の認証情報
data/repos/ クローンしたリポジトリ

コンテナを再作成（docker compose down && docker compose up -d）してもデータは保持されます。

DBマイグレーション

Docker Compose起動時、docker-entrypoint.sh がDBマイグレーションを自動実行します。バージョンが古いDBファイルがある場合も自動的に最新スキーマに更新されます。

Docker環境とは

ClaudeWorkはDocker実行環境をデフォルトとして使用します。Docker環境では、Claude Codeが独立したコンテナ内で動作するため、以下のメリットがあります。

  • セキュリティ隔離: Claude Codeの動作がコンテナ内に閉じ込められる
  • SSH鍵の自動マウント: ~/.ssh/ がコンテナに読み取り専用でマウントされ、プライベートリポジトリへのアクセスが可能
  • 独立した認証管理: 環境ごとに独立したClaude認証情報を保持

Docker環境は Settings → Environments から管理します。

環境の作成と管理

新しいDocker環境を作成する

  1. ClaudeWorkを起動: docker compose up -d
  2. ブラウザで http://localhost:3000 を開く
  3. Settings → Environments に移動
  4. "新しい環境を作成" をクリック
  5. 以下を設定:
    • 名前: 環境の識別名（例: "開発環境"）
    • 種別: "Docker" を選択
    • 必要に応じて権限スキップ、ポートマッピング、ボリュームマウントを設定
  6. "保存" をクリック

初回起動時にデフォルトのDocker環境が自動的に作成されます。

権限スキップオプション

--dangerously-skip-permissions は Claude Code の確認プロンプトをスキップするオプションです。Docker環境のみで利用可能です。Host環境では設定できません。

注意: このオプションは確認なしにファイルの読み書きや操作が実行されます。Docker環境のセキュリティ隔離と組み合わせて使用することを前提としています。

環境レベルでのデフォルト設定

環境全体のデフォルト動作を設定できます。

  1. Settings → Environments で対象のDocker環境を選択
  2. "編集" をクリック
  3. 権限スキップ トグルを有効にする
  4. "保存" をクリック

この設定を有効にすると、その環境を使用するすべてのセッションでデフォルトとして適用されます。

セッション単位でのオーバーライド

セッション作成時に、環境のデフォルト設定を上書きできます。

  1. プロジェクト画面で "新しいセッション" をクリック
  2. Docker環境を選択すると 権限スキップ の選択肢が表示される
  3. 以下から選択:
    • 環境デフォルト: 環境の設定に従う
    • 有効: このセッションのみ有効にする
    • 無効: このセッションのみ無効にする
  4. セッションを作成

ポートマッピング設定

コンテナ内で動作するサービスのポートをホストに公開できます。例えば、Claude Codeが起動したWebサーバーにブラウザからアクセスする場合に使用します。

ポートマッピングの追加

  1. Settings → Environments で対象のDocker環境を選択
  2. "編集" をクリック
  3. ポートマッピング セクションで "追加" をクリック
  4. 以下を入力:
    • ホストポート: ホスト側のポート番号（例: 8080）
    • コンテナポート: コンテナ側のポート番号（例: 3000）
    • プロトコル: tcp（デフォルト）または udp
  5. "保存" をクリック

設定例

用途 ホストポート コンテナポート プロトコル
Webサーバー 8080 3000 tcp
APIサーバー 8081 8000 tcp
UDP通信 9000 9000 udp

注意事項

  • 同じホストポートを複数の環境で使用するとポートが競合します
  • セッション起動中にポートマッピングを変更した場合は、設定の即時適用が必要です

ボリュームマウント設定

ホストのディレクトリやファイルをコンテナ内にマウントできます。コンテナ外のデータやツールにアクセスする場合に使用します。

ボリュームマウントの追加

  1. Settings → Environments で対象のDocker環境を選択
  2. "編集" をクリック
  3. ボリュームマウント セクションで "追加" をクリック
  4. 以下を入力:
    • ホストパス: マウントするホスト側のパス（例: /home/user/data）
    • コンテナパス: コンテナ内のマウント先パス（例: /mnt/data）
    • 読み取り専用: チェックするとコンテナからの書き込みを禁止（推奨）
  5. "保存" をクリック

危険なパスへの警告

以下のようなシステムの重要なパスをマウントしようとすると、警告ダイアログが表示されます。

  • / （ルートディレクトリ）
  • /etc
  • /var
  • /usr
  • /bin, /sbin
  • ホームディレクトリ全体（~ や /home/user）

警告が表示された場合は、マウントの必要性を慎重に検討してください。

設定例

用途 ホストパス コンテナパス 読み取り専用
データの共有 /home/user/data /mnt/data いいえ
設定ファイルの参照 /home/user/.config/tool /home/node/.config/tool はい
npm キャッシュの共有 /home/user/.npm /home/node/.npm いいえ

注意事項

  • コンテナは node ユーザー（ホームディレクトリは /home/node）で動作します。ホームディレクトリ配下へのマウントを行う場合は /home/node/... を使用してください
  • 書き込み可能なマウントでは、コンテナ内の操作がホストのファイルに影響します
  • セッション起動中にボリュームマウントを変更した場合は、設定の即時適用が必要です

設定の即時適用

ポートマッピングやボリュームマウントの変更は、起動中のセッションには自動で反映されません。実行中のセッションに変更を反映するには、即時適用機能を使用します。

注意: 即時適用を行うと、その環境を使用している実行中のセッションのコンテナが再作成されます。作業中の内容は保存されますが、実行中のプロセスは中断されます。

即時適用の手順

方法1: 環境一覧から適用

  1. Settings → Environments を開く
  2. 対象の環境カードにある "今すぐ適用" ボタンをクリック
  3. 確認ダイアログで影響を受けるセッション一覧を確認
  4. "適用" をクリック

方法2: 環境編集画面から適用

  1. Settings → Environments で対象の環境を選択し "編集" をクリック
  2. 設定を変更して "保存" をクリック
  3. "今すぐ適用" ボタンをクリック
  4. 確認ダイアログで "適用" をクリック

即時適用が不要なケース

  • まだセッションが作成されていない環境
  • 次回セッション作成時に新しい設定で起動されるため問題ない場合

この場合は、次回のセッション作成時から新しい設定が自動的に使用されます。