Docker + Streamlit UI 統合ガイド

概要

このガイドでは、Docker環境でMixseek Streamlit UIを実行する方法を説明します。

Docker環境の利点

依存関係の自動管理
環境の一貫性
ホストシステムの汚染を回避
本番環境デプロイの簡素化

対象読者

Docker開発環境を使用する開発者
Docker環境でMixseek UIをデプロイする運用担当者
CI/CD統合を行うDevOpsエンジニア

前提条件

Docker Engine 20.10以降
Make 4.0以降
Git（ソースコード取得用）

セットアップ

Step 1: 環境設定ファイルの準備

環境変数ファイル.env.devを作成します:

cp dockerfiles/dev/.env.dev.template .env.dev

.env.devを編集して必要な環境変数を設定:

# Mixseek Workspace
MIXSEEK_WORKSPACE=/workspace

# API Keys
ANTHROPIC_API_KEY=your-anthropic-api-key
GOOGLE_GEMINI_API_KEY=your-google-api-key

# Optional: Logfire
LOGFIRE_TOKEN=your-logfire-token

Step 2: Dockerイメージのビルド

開発用Dockerイメージをビルドします:

cd dockerfiles/dev
make build

ビルドには5-10分程度かかります。以下が含まれます:

Python 3.13.9 + uv
Node.js 22.20.0
AI開発ツール（Claude Code, Codex, Gemini CLI）
Mixseek-Core依存関係（streamlit, plotly, duckdb含む）

Step 3: コンテナの起動

バックグラウンドでコンテナを起動します:

make run

起動メッセージ:

🚀 Starting development container: mixseek-core-dev
✅ Development container started
💡 Connect with: make bash
💡 Start Streamlit UI: make streamlit
🔗 Container name: mixseek-core-dev
🔗 Exposed ports: 5678 (debug), 8501 (streamlit)

make runは以下を自動的に行います:

ポート5678（デバッグ）と8501（Streamlit）の公開
プロジェクトディレクトリの/appへのマウント
.cacheと.configディレクトリのマウント
.env.devの環境変数読み込み

Step 4: Streamlit UIの起動

コンテナ内でStreamlitを起動します:

export MIXSEEK_WORKSPACE=/path/to/workspace
make streamlit

出力:

🎨 Starting Streamlit UI (Feature 076-ui)
🔗 Streamlit will be available at http://localhost:8501
💡 Make sure container was started with: docker run -p 8501:8501 ...

ブラウザでhttp://localhost:8501にアクセスします。

Makefileターゲット

コンテナライフサイクル

make run       # コンテナを起動（バックグラウンド）
make stop      # コンテナを停止
make restart   # コンテナを再起動
make rm        # コンテナを削除
make status    # コンテナとイメージのステータス表示

シェルアクセス

make bash      # コンテナ内のbashシェルに接続
make root      # root権限でシェルに接続
make exec ARG='command'  # コンテナ内でコマンド実行

Streamlit UI

make streamlit # Streamlit UIを起動（対話モード）

開発ツール

make lint      # コードリンティング（ruff）
make format    # コードフォーマット（ruff）
make check     # 型チェック（mypy）
make unittest  # ユニットテスト実行

ポートマッピング

デフォルト公開ポート

make runは以下のポートを自動的に公開します:

ポート	用途	説明
5678	デバッグ	debugpy（Python デバッガー）
8501	Streamlit UI	Streamlit アプリケーション

カスタムポートマッピング

手動でポートを追加する場合:

docker run \
  --name mixseek-core-dev \
  -p 5678:5678 \
  -p 8501:8501 \
  -p 8888:8888 \
  -v $(pwd):/app \
  --env-file=.env.dev \
  -d mixseek-core/dev:latest

ワークスペースの永続化

ホスト側ディレクトリのマウント

ワークスペースをホスト側にマウントしてデータを永続化:

docker run \
  --name mixseek-core-dev \
  -p 8501:8501 \
  -v $(pwd):/app \
  -v $HOME/mixseek-workspace:/workspace \
  -e MIXSEEK_WORKSPACE=/workspace \
  --env-file=.env.dev \
  -d mixseek-core/dev:latest

この設定により、$HOME/mixseek-workspaceに保存されたデータは、コンテナを削除しても保持されます。

`.cache`と`.config`の永続化

make runは自動的に以下をマウントします:

-v $(ROOTDIR)/.cache:/home/appuser/.cache
-v $(ROOTDIR)/.config:/home/appuser/.config

これにより、uv依存関係キャッシュと設定ファイルが永続化されます。

本番デプロイ

ヘッドレスモード

本番環境では、Streamlitをヘッドレスモードで起動します:

mixseek ui \
  --server.headless true \
  --server.port 8501 \
  --server.address 0.0.0.0

Dockerfile例（本番用）

本番環境向けの軽量Dockerfileの例:

FROM python:3.13-slim

WORKDIR /app

# Install uv
RUN pip install uv

# Copy project files
COPY pyproject.toml uv.lock README.md ./
COPY src/ ./src/

# Install dependencies
RUN uv sync --frozen

# Set environment variables
ENV MIXSEEK_WORKSPACE=/workspace
ENV PYTHONUNBUFFERED=1

# Expose Streamlit port
EXPOSE 8501

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:8501/_stcore/health || exit 1

# Start Streamlit
CMD ["uv", "run", "streamlit", "run", "src/mixseek/ui/app.py", \
     "--server.headless", "true", \
     "--server.port", "8501", \
     "--server.address", "0.0.0.0"]

Docker Composeでのデプロイ

docker-compose.ymlの例:

version: '3.8'

services:
  mixseek-ui:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "8501:8501"
    volumes:
      - ./workspace:/workspace
    environment:
      - MIXSEEK_WORKSPACE=/workspace
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - GOOGLE_GEMINI_API_KEY=${GOOGLE_GEMINI_API_KEY}
    env_file:
      - .env.prod
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8501/_stcore/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

起動:

docker-compose up -d

CI/CD統合

GitHub Actions例

.github/workflows/ui-test.yml:

name: UI Test

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  ui-test:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Build Docker image
        run: |
          cd dockerfiles/dev
          make build

      - name: Start container
        run: |
          cd dockerfiles/dev
          make run

      - name: Run UI tests
        run: |
          cd dockerfiles/dev
          make exec ARG='pytest tests/ui/ -v'

      - name: Stop container
        if: always()
        run: |
          cd dockerfiles/dev
          make stop
          make rm

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

ポート8501が既に使用中

症状: コンテナ起動時にbind: address already in useエラー。

解決方法:

既存のコンテナまたはプロセスを確認:

docker ps | grep 8501
lsof -i :8501

既存のコンテナを停止:

docker stop <container-id>

または、別のポートを使用:

docker run -p 8502:8501 mixseek-core/dev:latest

ワークスペースマウントエラー

症状: permission deniedまたはcannot access /workspaceエラー。

解決方法:

ホスト側のディレクトリが存在するか確認:

ls -la $HOME/mixseek-workspace

ディレクトリが存在しない場合は作成:

mkdir -p $HOME/mixseek-workspace

UID/GID一致を確認（dockerfiles/dev/MakefileのMIXSEEK_UIDとMIXSEEK_GID）:

id -u  # ホスト側のUID
id -g  # ホスト側のGID

Streamlit起動失敗

症状: make streamlit実行時にエラー。

解決方法:

コンテナログを確認:

docker logs mixseek-core-dev

コンテナ内で手動実行:

make bash
mixseek ui --server.address 0.0.0.0

環境変数MIXSEEK_WORKSPACEが設定されているか確認:

make exec ARG='echo $MIXSEEK_WORKSPACE'

イメージビルド失敗

症状: make build時にエラー。

解決方法:

キャッシュをクリアして再ビルド:

make build-no-cache

.env.devファイルが存在するか確認:

ls -la .env.dev

Docker Engineのバージョン確認:

docker --version

セキュリティ考慮事項

APIキーの管理

.env.devファイルをGit管理下に含めないでください:

echo ".env.dev" >> .gitignore

本番環境では、環境変数をDocker Secretsまたは外部シークレット管理サービスで管理します。

非rootユーザー

開発用Dockerfileは非rootユーザー（appuser）で実行されます。これはセキュリティのベストプラクティスです。

ネットワーク分離

本番環境では、Streamlit UIをリバースプロキシ（Nginx, Traefik）の背後に配置し、認証を追加することを推奨します。

パフォーマンス最適化

uvキャッシュの活用

make runは.cacheディレクトリをマウントし、uv依存関係キャッシュを再利用します。これにより、コンテナ再起動時の依存関係インストール時間が短縮されます。

マルチステージビルド

本番用Dockerfileでは、マルチステージビルドを使用してイメージサイズを削減できます:

# Build stage
FROM python:3.13-slim AS builder
WORKDIR /app
RUN pip install uv
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen

# Runtime stage
FROM python:3.13-slim
WORKDIR /app
COPY --from=builder /app/.venv /app/.venv
COPY src/ ./src/
ENV PATH="/app/.venv/bin:$PATH"
CMD ["streamlit", "run", "src/mixseek/ui/app.py", "--server.headless", "true"]

Docker + Streamlit UI 統合ガイド

概要

Docker環境の利点

対象読者

前提条件

セットアップ

Step 1: 環境設定ファイルの準備

Step 2: Dockerイメージのビルド

Step 3: コンテナの起動

Step 4: Streamlit UIの起動

Makefileターゲット

コンテナライフサイクル

シェルアクセス

Streamlit UI

開発ツール

ポートマッピング

デフォルト公開ポート

カスタムポートマッピング

ワークスペースの永続化

ホスト側ディレクトリのマウント

.cacheと.configの永続化

本番デプロイ

ヘッドレスモード

Dockerfile例（本番用）

Docker Composeでのデプロイ

CI/CD統合

GitHub Actions例

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

ポート8501が既に使用中

ワークスペースマウントエラー

Streamlit起動失敗

イメージビルド失敗

セキュリティ考慮事項

APIキーの管理

非rootユーザー

ネットワーク分離

パフォーマンス最適化

uvキャッシュの活用

マルチステージビルド

関連ドキュメント

`.cache`と`.config`の永続化