はじめに¶

このページでは、Djangoプロジェクトをmagic-pocketでAWS Lambda上にデプロイする手順を説明します。 Admin画面がLambda上で動くところまでを目標にします。

事前準備¶

以下の3つが必要です。

Python パッケージマネージャー¶

magic-pocketはPyPIおよびGitHubからインストール可能です。 以下の例では uv を使います。他のツールを使う場合は、コマンドを適宜読み替えてください。

AWS アカウント¶

AWSアカウント が必要です。

credentialsは ~/.aws/credentials への設定を想定しています。 boto3のドキュメント を参考に設定してください。

データベース¶

以下のいずれかを選択してください。

• Neon: サーバーレス PostgreSQL。APIキーは環境変数 NEON_API_KEY で設定します。
• TiDB Serverless: MySQL 互換のサーバーレス DB。APIキーは環境変数 TIDB_PUBLIC_KEY / TIDB_PRIVATE_KEY で設定します。
• RDS Aurora PostgreSQL Serverless v2: AWS マネージド。外部アカウント不要で、[rds] セクションと VPC 設定のみで利用できます。
• Aurora DSQL: AWS マネージドのサーバーレス PostgreSQL 互換 DB。VPC 不要、IAM 認証。Django ORM / Loco との互換性が低いため、直接 SQL 実行向けです。

このガイドでは Neon を使った手順を説明します。TiDB を使う場合は「設定ファイル - tidb」、RDS を使う場合は「設定ファイル - rds」、DSQL を使う場合は「設定ファイル - dsql」を参照してください。

1. Djangoプロジェクトの作成¶

# Djangoプロジェクトを作成
uv init --python 3.12 your-project-name
cd your-project-name
uv add django
uv run django-admin startproject your_project_name .
uv run python manage.py runserver

localhost:8000 でDjangoが動くことを確認してください。

2. 依存パッケージの追加¶

# runtime ライブラリ (Lambda image にも入る)
uv add django-environ psycopg magic-pocket

# deploy CLI (`pocket` コマンド)。デプロイ時のみ必要なので dev グループ推奨
uv add --dev magic-pocket-cli

3. 初期設定の生成¶

pocket django init を実行すると、以下のファイルが自動生成されます。

• pocket.toml — デプロイ設定
• pocket.Dockerfile — Lambda用Dockerfile
• settings.py — 環境変数対応に書き換え（django-environが必要）
• .env — ローカル開発用の環境変数

# ローカル開発用
db.sqlite3
.env

# magic-pocket: deploy のたび再生成される副産物
/pocket.runtime.toml
/pocket_cache/

uv run pocket django init

生成される pocket.toml¶

[general]
region = "ap-southeast-1" # (1)!
stages = ["dev", "prod"] # (2)!

[s3] # (3)!

[neon] # (4)!
project_name = "dev-your-project-name"

[awscontainer] # (5)!
dockerfile_path = "pocket.Dockerfile"

[awscontainer.handlers.wsgi] # (6)!
command = "pocket.django.lambda_handlers.wsgi_handler"
[awscontainer.handlers.management] # (7)!
command = "pocket.django.lambda_handlers.management_command_handler"
timeout = 600

[dev.awscontainer.handlers.wsgi] # (8)!
apigateway = {}
[prod.awscontainer.handlers.wsgi]
apigateway = {}

[awscontainer.secrets.managed] # (9)!
SECRET_KEY = { type = "password", options = { length = 50 } }
DJANGO_SUPERUSER_PASSWORD = { type = "password", options = { length = 16 } }
DATABASE_URL = { type = "neon_database_url" }

[awscontainer.django.storages] # (10)!
default = { store = "s3", location = "media" }
staticfiles = { store = "s3", location = "static", static = true, manifest = true }

1. AWSリージョンを指定してください。Neon プロジェクトも同じリージョン（または近いリージョン）で作成してください。
2. devとprodの2ステージ構成です。
3. S3バケットを作成。バケット名はプロジェクト名+ステージ名から自動生成。
4. 既存の Neon プロジェクトにブランチ・DB を作成。プロジェクトは事前に Neon Console で作成してください。
5. Lambdaコンテナの設定。
6. WSGIハンドラーのLambda関数を作成。
7. マネジメントコマンド実行用のLambda関数（timeout 600秒）。
8. dev/prod各環境にAPI Gatewayを設定。URLはAWSが自動生成。独自ドメインの場合は apigateway = { domain = "example.com" } と指定。
9. SECRET_KEY、スーパーユーザーパスワード、DB接続URLを自動生成しシークレットストアに保存。
10. S3上の media と static ディレクトリをDjangoのSTORAGESとして利用。

生成される .env¶

DEBUG=true
SECRET_KEY=ランダムに生成された値
DATABASE_URL=sqlite:///db.sqlite3

settings.py への変更¶

以下のコードが追加され、環境変数とpocket.tomlから設定を読み込むようになります。

from pocket.django.runtime import set_envs
from pocket.django.utils import get_caches, get_storages

STORAGES = get_storages()
CACHES = get_caches()

environ.Env.read_env(BASE_DIR / ".env")
env = environ.Env(
    SECRET_KEY=str,
    DEBUG=(bool, False),
    ALLOWED_HOSTS=(list, []),
)

set_envs()
SECRET_KEY = env.str("SECRET_KEY")
DEBUG = env.bool("DEBUG")
DATABASES = {"default": env.db()}
ALLOWED_HOSTS = env.list("ALLOWED_HOSTS")

4. NEON_API_KEY の設定¶

.env に NEON_API_KEY を追加します。

# .env に追記
NEON_API_KEY=あなたのNeon APIキー

5. デプロイ¶

dev環境¶

# デプロイ（インフラ構築 + コンテナイメージの作成・アップロード）
uv run pocket deploy --stage=dev

# Djangoの初期設定
uv run pocket django manage migrate --stage=dev
uv run pocket django manage collectstatic --noinput --stage=dev
uv run pocket django manage createsuperuser --username=admin --email=admin@example.com --noinput --stage=dev

自動生成されたシークレット（superuserのパスワード等）は以下で確認できます。

uv run pocket resource awscontainer secrets list --stage=dev --show-values

prod環境¶

同じコマンドで --stage=prod に変えるだけです。環境・シークレットは全て別になります。

uv run pocket deploy --stage=prod
uv run pocket django manage migrate --stage=prod
uv run pocket django manage collectstatic --noinput --stage=prod
uv run pocket django manage createsuperuser --username=admin --email=admin@example.com --noinput --stage=prod