Skip to content

setup.md

Latest commit

 

History

History
375 lines (266 loc) · 7.84 KB

setup.md

File metadata and controls

375 lines (266 loc) · 7.84 KB

セットアップガイド

このドキュメントでは、データサイエンス開発環境の詳細なセットアップ手順を説明します。

目次

  1. 前提条件
  2. 初期セットアップ
  3. DevContainerの使用
  4. Dockerコマンドでの使用
  5. 環境設定
  6. パッケージ管理
  7. よくあるトラブルと解決策

前提条件

必須ソフトウェア

  • Docker Desktop: 公式サイトからインストール

    • Windows: WSL2バックエンドを有効化
    • Mac: Apple Silicon/Intel両対応
    • Linux: Docker EngineとDocker Compose

  • Visual Studio Code: 公式サイトからインストール

推奨VSCode拡張機能

以下の拡張機能をインストールしてください：

ms-vscode-remote.remote-containers
ms-python.python
ms-toolsai.jupyter

システム要件

  • RAM: 最低8GB（16GB推奨）
  • ストレージ: 10GB以上の空き容量
  • CPU: 4コア以上推奨

初期セットアップ

1. リポジトリのクローン

git clone <repository-url>
cd DataScience_Starter_Docker

2. 環境変数の設定

# 環境変数ファイルをコピー
cp .env.example .env

# .envファイルを編集
# 必要に応じて以下の値を設定：
# - API Keys (OpenAI, HuggingFace等)
# - データベース接続情報
# - AWS認証情報

3. UID/GIDの設定（Linux/Mac）

現在のユーザーのUID/GIDを確認して設定：

# UIDとGIDを確認
id -u  # UID
id -g  # GID

# .envに追加
echo "USER_UID=$(id -u)" >> .env
echo "USER_GID=$(id -g)" >> .env

DevContainerの使用

VSCodeでの起動手順

  1. VSCodeでプロジェクトフォルダを開く
  2. コマンドパレットを開く（Cmd/Ctrl + Shift + P）
  3. "Dev Containers: Reopen in Container"を選択
  4. 初回起動時はイメージのビルドに数分かかります

DevContainer内での作業

コンテナ内では以下のコマンドが利用可能：

# Pythonパッケージの確認
uv pip list

# Jupyter Labの起動
jupyter lab --ip=0.0.0.0 --port=8888

# Pythonスクリプトの実行
python src/main.py

# テストの実行
pytest tests/

Dockerコマンドでの使用

VSCodeを使わない場合の手順：

コンテナのビルドと起動

# イメージのビルド
docker compose build

# コンテナの起動（バックグラウンド）
docker compose up -d

# コンテナに接続
docker compose exec app bash

コンテナの停止と削除

# コンテナの停止
docker compose stop

# コンテナの削除
docker compose down

# ボリュームも含めて削除
docker compose down -v

環境設定

Jupyter Labの設定

# パスワードの生成
jupyter lab password

# 設定ファイルの生成
jupyter lab --generate-config

Streamlitアプリの実行

# アプリの起動
streamlit run app/main.py

# カスタムポートで起動
streamlit run app/main.py --server.port 8502

GPUの使用（NVIDIA GPU搭載環境）

  1. NVIDIA Docker Toolkitをインストール
  2. compose.ymlに以下を追加：
services:
  app:
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

パッケージ管理

追加ライブラリのインストール方法

作業中に新しいライブラリが必要になった場合、以下の手順でインストールできます：

コンテナ内での一時的なインストール

# コンテナ内でライブラリを追加（一時的）
uv add scikit-learn seaborn

# または特定のバージョンを指定
uv add "transformers>=4.21.0"

永続化のためのファイル更新

# pyproject.tomlを更新して永続化
uv add --group main scikit-learn seaborn

# 開発用パッケージとして追加
uv add --group dev pytest-cov mypy

# 変更をコミット
git add pyproject.toml uv.lock
git commit -m "Add new dependencies"

uvを使用したパッケージ管理

# パッケージの追加
uv add numpy pandas matplotlib

# 開発用パッケージの追加
uv add --dev pytest black ruff

# 特定バージョンの指定
uv add "numpy>=1.24,<2.0"

# requirements.txtからのインストール
uv pip install -r requirements.txt

# パッケージの削除
uv remove package-name

# 依存関係の更新
uv sync

オプショナルパッケージのインストール

# NLP関連パッケージ
uv sync --extra nlp

# コンピュータビジョン関連
uv sync --extra cv

# 開発ツール
uv sync --extra dev

よくあるトラブルと解決策

1. Dockerコンテナが起動しない

症状: docker compose upでエラーが発生

解決策:

# Dockerデーモンの確認
docker version

# Docker Desktopを再起動
# システムトレイのアイコンから"Restart"を選択

# キャッシュクリア
docker system prune -a

2. パーミッションエラー（Linux）

症状: ファイルの作成・編集でパーミッションエラー

解決策:

# .envでUID/GIDを正しく設定
USER_UID=1000
USER_GID=1000

# コンテナを再ビルド
docker compose down
docker compose build --no-cache
docker compose up

3. メモリ不足エラー

症状: 大規模データ処理時にメモリエラー

解決策:

  • Docker Desktopの設定でメモリ割り当てを増やす
    • Settings → Resources → Memory
    • 最低8GB、推奨16GB以上

4. ポート競合

症状: "port is already allocated"エラー

解決策:

# 使用中のポートを確認
lsof -i :8888  # Mac/Linux
netstat -ano | findstr :8888  # Windows

# compose.ymlでポート番号を変更
ports:
  - "8889:8888"  # 8889に変更

5. uvパッケージインストールエラー

症状: パッケージのインストールが失敗

解決策:

# キャッシュクリア
uv cache clean

# ロックファイルの再生成
rm uv.lock
uv sync

# 仮想環境の再作成
rm -rf .venv
uv venv
uv sync

6. Jupyter Labに接続できない

症状: ブラウザからJupyter Labにアクセスできない

解決策:

# トークンを確認
jupyter lab list

# ファイアウォール設定を確認
# Windowsの場合、Windows Defenderで8888ポートを許可

# 別のポートで起動
jupyter lab --port=8889

高度な設定

マルチステージビルドの活用

本番環境用の軽量イメージを作成：

# Dockerfileに追加
FROM python:3.11-slim as production
COPY --from=builder /app/.venv /app/.venv
COPY --from=builder /app/src /app/src

CI/CD設定

GitHub Actionsの設定例：

# .github/workflows/test.yml
name: Test
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Build and test
        run: |
          docker compose build
          docker compose run app pytest

サポート

問題が解決しない場合は、以下の方法でサポートを受けてください：

  1. GitHubのIssueを作成
  2. エラーメッセージとログを含めて報告
  3. 使用環境（OS、Dockerバージョン等）を明記

関連リンク