🍷

uvとdirenvで作るクリーンなAWS Chalice開発環境@WSL

に公開
AWS
Amazon API Gateway
AWS Lambda
Chalice
uv
tech

この記事について

AWS Chaliceの開発環境を、モダンなPythonツール「uv」とWSL環境で構築する手順を紹介します。

  • ✅ direnvによる環境変数の自動管理
  • ✅ uvによる高速な依存関係管理
  • ✅ 公式手順より浅い階層構造(※)

(※)実際にやってみるとhelloworldディレクトリが邪魔くさいです(笑)

対象読者

  • AWS Lambdaでサーバーレスアプリを作りたい方
  • Chaliceに興味がある方
  • 公式手順の階層の深さに違和感を持った方

前提条件

以下がインストール済みであることを前提とします:

  • WSL2 (Ubuntu推奨)
  • uv
  • direnv
  • 基本ツール (curl, git, build-essential)
前提条件のインストール手順
# システムアップデート
sudo apt update && sudo apt upgrade -y

# 基本ツール
sudo apt install -y curl git build-essential

# uvのインストール
curl -LsSf https://astral.sh/uv/install.sh | sh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

# direnvのインストールと設定
sudo apt install -y direnv
echo 'eval "$(direnv hook bash)"' >> ~/.bashrc

# 設定を反映
source ~/.bashrc

環境構築手順

1. プロジェクトの作成

公式手順との違い: chalice new-project は使わず、uvで直接プロジェクトを作成します。

# プロジェクトディレクトリ作成
mkdir -p ~/workspace/chalice-tutorial
cd ~/workspace/chalice-tutorial

# uvでPythonプロジェクトを初期化
uv init --python 3.13

# Chaliceを依存関係に追加
uv add chalice

これで、プロジェクトルート直下に app.py を配置できます。

2. AWS認証情報の設定

direnvを使って環境変数を管理します。

# .envrcファイルを作成
cat > .envrc << 'EOF'
export AWS_ACCESS_KEY_ID=your-access-key-id
export AWS_SECRET_ACCESS_KEY=your-secret-access-key
export AWS_DEFAULT_REGION=ap-northeast-1
EOF

# direnvで許可
direnv allow

# ディレクトリを出入りして環境変数を読み込む
cd .. && cd chalice-tutorial

# 確認
echo $AWS_ACCESS_KEY_ID

echo ".envrc" >> .gitignore

3. Chaliceアプリケーションの作成

最小構成のアプリケーションを作成します。

# app.pyの作成
cat > app.py << 'EOF'
from chalice.app import Chalice

app = Chalice(app_name='chalice-tutorial')

@app.route('/')
def index():
    return {'hello': 'world'}
EOF

Chaliceの設定ファイルを作成:

mkdir -p .chalice

cat > .chalice/config.json << 'EOF'
{
  "version": "2.0",
  "app_name": "chalice-tutorial",
  "stages": {
    "dev": {
      "api_gateway_stage": "api"
    }
  }
}
EOF

依存関係管理用の空ファイルを作成:

touch requirements.txt

Chaliceはデプロイ時にrequirements.txtを参照して依存関係をパッケージングするため、たとえ現時点では空でもこのファイルを作成しておく必要があります。

.gitignore にChalice関連のファイルを追加:

cat >> .gitignore << 'EOF'

# Chalice
.chalice/deployments/
.chalice/venv/
EOF

動作確認

ローカルでのテスト

プロジェクトルートから直接実行できます:

# ローカルサーバー起動
uv run chalice local

別のターミナルでアクセスしてみます:

curl http://localhost:8000/
# => {"hello":"world"}

AWSへのデプロイ

uv run chalice deploy

デプロイが成功すると、APIのエンドポイントURLが表示されます:

Creating deployment package.
Creating IAM role: chalice-tutorial-dev
Creating lambda function: chalice-tutorial-dev
Creating Rest API
Resources deployed:
  - Lambda ARN: arn:aws:lambda:ap-northeast-1:xxxx:function:chalice-tutorial-dev
  - Rest API URL: https://xxxxxxxxxx.execute-api.ap-northeast-1.amazonaws.com/api/

ブラウザやcurlでアクセスして動作確認できます。

よく使うコマンド

# ログ確認
uv run chalice logs

# エンドポイントURL表示
uv run chalice url

# リソース削除
uv run chalice delete

プロジェクト構造

最終的なディレクトリ構造:

chalice-tutorial/        # プロジェクトルート
├── .chalice/
│   ├── config.json
│   └── deployments/    # デプロイ後に作成される
├── .venv/              # uvが管理
├── app.py
├── requirements.txt
├── pyproject.toml
├── .python-version
├── .envrc              # git管理対象外
├── .gitignore
└── README.md

公式手順との比較:

項目 公式手順 この記事の手順
プロジェクト構造 project/helloworld/app.py project/app.py
階層の深さ 深い 浅い
コマンド実行 cd helloworld 必要 ルートから実行可能
uv/Poetry統合 やや煩雑 自然

この構成のメリット

1. フラットな構造

プロジェクトルート = Chaliceアプリのため、ファイル移動が少なく直感的です。

# 公式手順
cd my-project/helloworld
vim app.py

# この構成
cd my-project
vim app.py              # シンプル!

2. 依存関係の明確化

requirements.txt は Lambda にデプロイする依存関係のみを記述します。開発ツールは pyproject.toml で管理されるため、混在しません。chaliceコマンド自体は開発環境で利用するツールであり、Lambdaにデプロイされるアプリケーションコードの依存関係はrequirements.txtで管理します

# requirements.txt - Lambda用
requests
boto3

# pyproject.toml - 開発環境用
# chalice
# pytest
# ruff

3. 高速な環境構築

uvによる高速なパッケージ管理で、環境構築が短時間で完了します。

トラブルシューティング

direnvが動かない

# bashに統合されているか確認
grep direnv ~/.bashrc

# なければ追加
echo 'eval "$(direnv hook bash)"' >> ~/.bashrc
source ~/.bashrc

環境変数が読み込まれない

# ディレクトリを出入りする
cd .. && cd chalice-tutorial

# ステータス確認
direnv status

# 手動で許可
direnv allow

Python 3.14の警告

Lambda は Python 3.13 までしかサポートしていません。

echo "3.13" > .python-version
rm -rf .venv
uv sync

まとめ

公式手順の chalice new-project をスキップし、uvで直接プロジェクトを作成することで:

  • ✅ フラットな階層構造
  • ✅ モダンなPythonツールチェインとの自然な統合
  • ✅ direnvによるクリーンな環境変数管理

を実現できました。

この環境をベースに、DynamoDB連携やAPI認証など、本格的なサーバーレスアプリケーション開発に進めます。

参考リンク

Discussion