fly-io

Fly.io

このスキルでは、初期設定、データベース管理、CI/CD 統合、本番環境の運用など、Fly.io へのアプリケーションのデプロイに関する包括的なガイダンスを提供します。

使用するタイミング

以下の作業を行うと、このスキルが自動的に有効になります。

• Fly.io 固有のタスク（「fly.io」、「deploy to fly」、「fly.io setup」、「flyctl」）
• Fly.io の設定（「fly.toml」、「fly app」、「fly launch」）
• Fly.io のデータベース操作（「fly postgres」、「fly pg」）
• Fly.io の環境管理（「fly secrets」、「fly env」）
• Fly.io のモニタリング（「fly logs」、「fly status」、「fly dashboard」）
• Fly.io の GitHub Actions（「fly deploy github action」、「flyctl in CI/CD」）

基本原則

1. セキュリティを最優先：機密データは必ず暗号化し、暗号化されていないシークレットは決してコミットしないでください
2. データベースの安全性：データベースへのアクセスにはプロキシを使用し、定期的にバックアップしてください
3. 環境の分離：開発、ステージング、本番の設定を分離してください
4. コストの把握：リソースの割り当てを最適化し、使用状況を定期的に確認してください
5. 自動化：一貫性があり、再現可能なデプロイには CI/CD を活用してください
6. モニタリング：包括的なログ記録とヘルスチェックを実装してください

前提条件

Fly.io へのデプロイを始める前に、以下を準備してください。

1. Fly.io アカウント：クレジットカードを登録した有効なアカウント（PostgreSQL に必要）
2. CLI のインストール：flyctl コマンドラインツールをインストールし、認証を済ませてください
3. 環境変数：プロジェクト固有の設定を準備してください
4. アプリケーションの準備：本番環境へのデプロイに向けてアプリケーションを設定してください

手順

1. 初期設定と認証

Fly.io CLI をインストールする：

# Standard installation
curl -L https://fly.io/install.sh | sh

# Add to PATH (adjust based on your environment)
export FLYCTL_INSTALL="/home/user/.fly"
export PATH="$FLYCTL_INSTALL/bin:$PATH"

# Verify installation
flyctl version

Fly.io で認証する：

flyctl auth login

認証用のブラウザーが開きます。ログインに成功すると、認証情報がローカルに保存されます。

2. 環境変数の管理

セキュリティのための暗号化：

機密データを保護するため、Fly.io へのデプロイでは暗号化された環境変数ファイルを使用してください。

# Decrypt environment file (requires ENV_PASS variable)
openssl enc -aes-256-cbc -pbkdf2 -salt -d -in .env.enc -out .env -k $ENV_PASS

# After modifying .env, re-encrypt
openssl enc -aes-256-cbc -pbkdf2 -salt -in .env -out .env.enc -k $ENV_PASS

# For production environment
openssl enc -aes-256-cbc -pbkdf2 -salt -in .env -out .env.enc.prod -k $ENV_PASS

セキュリティに関する重要な注意事項：

• 暗号化されていない .env ファイルは決してコミットしないでください
• ENV_PASS は安全に保管してください（GitHub シークレット、パスワードマネージャーなど）
• ステージング環境と本番環境では、異なる暗号化パスワードを使用してください
• まだ設定されていない場合は、.env を .gitignore に追加してください

3. データベースの設定（PostgreSQL）

PostgreSQL データベースを作成する：

# Create new PostgreSQL database on Fly.io
flyctl postgres create

# When prompted, use naming convention: {project-name}-db
# Example: myapp-db

データベース作成時の重要なオプション：

• ユーザーに最も近いリージョンを選択してください
• 適切なリソースティアを選択してください（小規模から開始し、必要に応じて拡張します）
• 提供されたデータベースの認証情報を控えてください
• データベース名には通常、アプリ名に「-db」を付けた名前を使用します

データベースをアプリケーションに接続する：

# Attach database to your application
flyctl pg attach {project-name}-db -a {project-name}

# If attachment fails, set DATABASE_URL manually
flyctl secrets set DATABASE_URL=postgres://user:pass@host:5432/dbname -a {project-name}

データベース接続を確認する：

# Check database status
flyctl status -a {project-name}-db

# Test connection via proxy
flyctl proxy 5433 -a {project-name}-db
# In another terminal: psql -h localhost -p 5433 -U {username} -d {dbname}

4. アプリケーションの作成と設定

新しいアプリケーションを起動する：

# Create application (don't deploy yet)
flyctl launch

# Follow prompts:
# - Choose app name (matches ENV_NAME variable)
# - Select region (same as database for best performance)
# - Choose resource allocation
# - Decline immediate deployment (configure first)

アプリケーションを設定する：

flyctl launch の実行後、fly.toml を確認し、必要に応じてカスタマイズしてください。

app = "your-app-name"

[build]
  # Adjust based on your application type

[env]
  PORT = "8080"
  HOST = "::"
  # Add other non-secret environment variables

[http_service]
  internal_port = 8080
  force_https = true
  auto_stop_machines = true
  auto_start_machines = true
  min_machines_running = 0

シークレットを設定する：

# Set individual secrets
flyctl secrets set APP_KEYS="your-app-keys" -a {project-name}
flyctl secrets set API_TOKEN_SALT="your-salt" -a {project-name}

# Import from .env file (ensure it's decrypted first)
flyctl secrets import -a {project-name} < .env

5. デプロイのワークフロー

デプロイ前のチェックリスト：

• 環境変数が設定されている（本番環境の値）
• データベースが作成され、接続されている
• fly.toml を確認し、カスタマイズしている
• flyctl secrets でシークレットを設定している
• アプリケーションがローカルで正常にビルドできる
• 依存関係が本番環境で使用できる状態になっている

初回デプロイ：

# Deploy application
flyctl deploy -a {project-name}

# Monitor deployment
flyctl logs -a {project-name}

# Check status
flyctl status -a {project-name}

デプロイ後の確認：

# Open application in browser
flyctl open -a {project-name}

# Check health endpoint
curl https://{project-name}.fly.dev/health

# Review logs for errors
flyctl logs -a {project-name}

6. ドメインと SSL の設定

カスタムドメインを追加する：

# Add certificate for custom domain
flyctl certs create yourdomain.com -a {project-name}

# Check certificate status
flyctl certs show yourdomain.com -a {project-name}

DNS の設定：

1. ドメインの A/AAAA レコードを Fly.io に向けます
2. DNS の伝播を待ちます
3. 証明書が発行されたことを確認します
4. APP_URL 環境変数をカスタムドメインに更新します
5. 更新した設定で再デプロイします

7. データベースの管理

PostgreSQL のダンプ（バックアップ）：

# Standard dump format (custom format, compressed)
pg_dump -Fc --no-acl --no-owner -h HOST -U USERNAME -d DATABASE_NAME > dump_file.dump

# Example for local database
pg_dump -Fc --no-acl --no-owner -h localhost -U postgres -d strapi > backup.dump

PostgreSQL の復元：

# Standard restore
pg_restore --verbose --clean --no-acl --no-owner -h HOST -p PORT -U USERNAME -d "DATABASE_NAME" dump_file.dump

# Example for local database
pg_restore --verbose --clean --no-acl --no-owner -h localhost -U postgres -d strapi backup.dump

ローカルのデータベースを Fly.io にアップロードする：

# 1. Export local database
pg_dump -Fc --no-acl --no-owner -h localhost -U postgres -d {dbname} > latest.dump

# 2. Proxy production database (run in separate terminal)
flyctl proxy 5433 -a {project-name}-db

# 3. In another terminal, restore to production
DB_USER={check_fly_dashboard}  # Get from Fly.io dashboard
DB_NAME={check_fly_dashboard}   # Get from Fly.io dashboard
pg_restore --verbose --clean --no-acl --no-owner -h localhost -p 5433 -U $DB_USER -d "$DB_NAME" latest.dump

# 4. Clean up
rm latest.dump

本番データベースを Fly.io からダウンロードする：

# 1. Proxy production database (run in separate terminal)
flyctl proxy 5433 -a {project-name}-db

# 2. In another terminal, dump production database
DB_USER={check_fly_dashboard}
DB_NAME={check_fly_dashboard}
pg_dump -Fc --no-acl --no-owner -h localhost -p 5433 -U $DB_USER -d "$DB_NAME" > production.dump

# 3. Restore to local database
pg_restore --verbose --clean --no-acl --no-owner -h localhost -U postgres -d {dbname} production.dump

# 4. Clean up
rm production.dump

直接アクセス用のデータベースプロキシ：

# Proxy database to local port
flyctl proxy 5433 -a {project-name}-db

# Connect with psql
psql -h localhost -p 5433 -U {username} -d {dbname}

# Connect with GUI tools (PgAdmin, DBeaver, etc.)
# Host: localhost
# Port: 5433
# User: {from Fly.io dashboard}
# Database: {from Fly.io dashboard}

8. GitHub Actions CI/CD の統合

継続的デプロイの設定：

1. Fly.io API トークンを生成します：

   flyctl auth token
   

2. GitHub リポジトリのシークレットを追加します：

   • FLY_API_TOKEN：Fly.io API トークン
   • ENV_PASS：環境の暗号化パスワード（暗号化された .env を使用する場合）

3. .github/workflows/deploy.yml を作成します：

name: Deploy to Fly.io

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Fly.io CLI
        uses: superfly/flyctl-actions/setup-flyctl@master

      - name: Decrypt environment variables
        run: |
          openssl enc -aes-256-cbc -pbkdf2 -salt -d \
            -in .env.enc.prod -out .env -k ${{ secrets.ENV_PASS }}

      - name: Deploy to Fly.io
        run: flyctl deploy --remote-only
        env:
          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}

CI/CD のベストプラクティス：

• --remote-only フラグを使用して、Fly.io サーバー上でビルドします
• ステージング用と本番用のワークフローを分けます
• デプロイ後にスモークテストを実施します
• デプロイ状況を通知する Slack／Discord 通知を設定します
• 本番デプロイの承認ゲートに GitHub environments を使用します

9. モニタリングとトラブルシューティング

基本的なモニタリングコマンド：

# Check application status
flyctl status -a {project-name}

# View real-time logs
flyctl logs -a {project-name}

# View logs with filtering
flyctl logs -a {project-name} --region iad

# Check database status
flyctl status -a {project-name}-db

# View metrics
flyctl metrics -a {project-name}

# SSH into application
flyctl ssh console -a {project-name}

よくある問題と解決方法：

1. ポート設定の問題：

   • fly.toml の internal_port がアプリケーションの PORT と一致することを確認します
   • IPv6 との互換性のため、HOST が "::" に設定されていることを確認します
   • APP_URL がデプロイ先のドメイン／URL と一致することを確認します

2. データベース接続の失敗：

   • DATABASE_URL の形式と認証情報を確認します
   • データベースがアプリと同じリージョンにあることを確認します
   • プロキシ経由で接続をテストします：flyctl proxy 5433 -a {project-name}-db
   • データベースのログを確認します：flyctl logs -a {project-name}-db

3. 環境変数の問題：

   • シークレットが設定されていることを確認します：flyctl secrets list -a {project-name}
   • 暗号化する前に、.env 内の本番用の値を確認します
   • 復号時に ENV_PASS が正しいことを確認します
   • 変更後にシークレットを再インポートします：flyctl secrets import

4. デプロイの失敗：

   • ビルドログを確認します：flyctl logs -a {project-name}
   • Dockerfile またはビルドパックの設定を確認します
   • package.json／requirements.txt にすべての依存関係が含まれていることを確認します
   • デプロイ前にローカルでビルドをテストします
   • 必要に応じてビルドのタイムアウトを延長します

5. アプリケーションのクラッシュ：

   • エラーメッセージがないかログを確認します：flyctl logs -a {project-name}
   • ヘルスチェックのエンドポイントが応答していることを確認します
   • リソースの割り当て（メモリ、CPU）を確認します
   • データベース接続の問題がないか確認します
   • コンテナに SSH 接続してデバッグします：flyctl ssh console -a {project-name}

10. スケーリングとパフォーマンス

垂直スケーリング（リソース割り当て）：

# Scale VM resources
flyctl scale vm shared-cpu-1x --memory 512 -a {project-name}

# Available VM sizes:
# shared-cpu-1x (256MB, 512MB, 1GB, 2GB)
# dedicated-cpu-1x (2GB, 4GB, 8GB)
# dedicated-cpu-2x (4GB, 8GB, 16GB)

水平スケーリング（マシン数）：

# Scale number of machines
flyctl scale count 2 -a {project-name}

# Auto-scaling configuration in fly.toml:
[http_service]
  auto_stop_machines = true
  auto_start_machines = true
  min_machines_running = 0  # Scale to zero when idle

リージョンへのデプロイ：

# Add machines in multiple regions
flyctl regions add iad lhr syd -a {project-name}

# View current regions
flyctl regions list -a {project-name}

# Remove regions
flyctl regions remove lhr -a {project-name}

11. コストの最適化

コスト削減のための戦略：

1. 自動停止／自動起動：アイドル期間中にゼロまでスケールできるよう、fly.toml で有効にします
2. 適切なリソースサイズ：最小の VM サイズから始め、必要な場合にのみスケールアップします
3. データベースの最適化：適切な PostgreSQL ティアを選択し、使用状況を監視します
4. リージョン戦略：アクティブユーザーがいるリージョンにのみデプロイします
5. モニタリング：Fly.io ダッシュボードで請求アラートを設定します

コストのモニタリング：

# View current usage and costs
flyctl dashboard

# Check resource allocation
flyctl status -a {project-name}
flyctl status -a {project-name}-db

関連ファイル

このスキルには、次の関連テンプレートが含まれています：

• fly.toml.template：Fly.io の基本設定テンプレート
• deployment-checklist.md：デプロイ前の確認チェックリスト
• github-actions-workflow.yml：CI/CD ワークフローのサンプル

次の場所からアクセスできます：.claude/skills/flyio-deployment/templates/

よくあるデプロイパターン

パターン 1：本番環境への初回デプロイ

# 1. Setup and authenticate
flyctl auth login

# 2. Create database
flyctl postgres create  # Use {project-name}-db

# 3. Launch application
flyctl launch  # Don't deploy yet

# 4. Attach database
flyctl pg attach {project-name}-db -a {project-name}

# 5. Set secrets
flyctl secrets import -a {project-name} < .env

# 6. Deploy
flyctl deploy -a {project-name}

# 7. Verify
flyctl open -a {project-name}
flyctl logs -a {project-name}

パターン 2：データベースのマイグレーション

# Export from source
pg_dump -Fc --no-acl --no-owner -h {source-host} -U {user} -d {db} > migration.dump

# Proxy Fly.io database
flyctl proxy 5433 -a {project-name}-db  # Separate terminal

# Import to Fly.io
pg_restore --verbose --clean --no-acl --no-owner \
  -h localhost -p 5433 -U {user} -d {db} migration.dump

# Verify
flyctl ssh console -a {project-name}
# Inside container: run database query to verify data

パターン 3：デプロイのロールバック

# List recent releases
flyctl releases -a {project-name}

# Rollback to previous version
flyctl releases rollback -a {project-name}

# Or rollback to specific version
flyctl releases rollback {version-number} -a {project-name}

# Monitor rollback
flyctl logs -a {project-name}

セキュリティのベストプラクティス

1. 環境の暗号化：コミットする前に、必ず .env ファイルを暗号化します
2. データベースアクセス：公開せずに、データベースプロキシを使用します
3. API トークン：Fly.io API トークンは GitHub のシークレットに保存し、コードには絶対に記載しません
4. SSL 証明書：fly.toml で必ず force_https を有効にします
5. データベースのバックアップ：自動バックアップ戦略（S3、外部ストレージ）を導入します
6. シークレットのローテーション：API トークン、データベースのパスワード、暗号化キーを定期的にローテーションします
7. アクセス制御：チームのアクセス管理に Fly.io organizations を使用します
8. ネットワークセキュリティ：ファイアウォールルールを設定し、データベースへのアクセスを制限します

検証チェックリスト

デプロイの完了と判断する前に、以下を確認してください。

• アプリケーションに公開 URL からアクセスできる
• ヘルスチェックエンドポイントが正しく応答する
• データベース接続が機能している
• すべての環境変数が正しく設定されている
• SSL 証明書が発行され、有効になっている
• ログにエラーが表示されていない
• CI/CD パイプラインが設定され、テストされている
• データベースのバックアップが設定されている
• モニタリングとアラートが設定されている
• デプロイ URL と手順を反映してドキュメントが更新されている

実運用での注意点（苦い経験から学んだこと）

高リスクアカウントのロック

Fly.io は休眠アカウントを「高リスク」と判定します。アプリやデータベースの作成に失敗し、次のメッセージが表示されます。

Your account has been marked as high risk. Please go to https://fly.io/high-risk-unlock

解決方法：Fly アカウントにログインしたブラウザーで、この URL にアクセスする必要があります。CLI では回避できません。

自動停止の動作は積極的です

auto_stop_machines = "stop" と min_machines_running = 0 を設定すると、アイドル状態が約60秒続いた後にマシンが停止します。一部のフレームワークでは、コールドブートに5〜10秒かかります。そのため、次のことが起こります。

• アイドル状態の後の最初のリクエストは、起動処理の分だけ遅くなります
• API を短時間に連続して呼び出すと、呼び出しの合間にマシンが停止する場合があります
• バッチ操作を実行する前に、必ず /_health にアクセスし、204 が返るまで待ってください

Fly はデフォルトで2台のマシンを作成します

min_machines_running = 0 に設定していても、Fly は「HA」のために fly deploy でマシンを2台作成します。開発環境やステージング環境では、2台目を破棄してください。

fly status --app <app>  # Find both machine IDs
fly machine stop <second-id> --app <app>
fly machine destroy <second-id> --app <app> --force

内部ネットワークでは DATABASE_SSL を False にする必要があります

fly postgres attach は sslmode=disable を含む DATABASE_URL を設定します。アプリに DATABASE_SSL 環境変数がある場合は、false に設定してください。

[env]
  DATABASE_SSL = "false"

DNS と証明書の設定（Cloudflare）

DNS に Cloudflare を使用する場合：

1. レコードのプロキシを無効にする必要があります（proxied=false）。TLS 終端のため、Fly は直接トラフィックを受け取る必要があります
2. 古いレコードがないか確認してください。以前のデプロイで、プロキシが有効な A/AAAA レコードが残っている場合があります。まず削除してください
3. ACME CNAME — fly certs setup で _acme-challenge の CNAME ターゲットが提示されます。Let's Encrypt の検証用に作成または更新してください
4. DNS が正しく設定されていれば、証明書はすぐに（約30秒で）発行されます

デプロイフラグ：--region はありません

--primary-region を使用するか、fly.toml で primary_region を設定してください。fly deploy に --region フラグはありません。

Bash のトークンパイプ処理の不具合

長い API トークン（256文字以上）を、Bash の変数展開と curl を使ってパイプ処理すると、標準出力が空になります。次の方法で回避できます。

• トークンをファイルに保存する：echo -n "TOKEN" > /tmp/.token && TK=$(cat /tmp/.token)
• パイプを使わず、curl に -o file を指定する
• Python の urllib.request を使用する（サンドボックス環境では最も信頼性が高い方法です）

追加リソース

• Fly.io 公式ドキュメント
• Fly.io CLI リファレンス
• Fly.io 料金
• Fly.io コミュニティフォーラム
• GitHub Actions との統合

備考

• 本番環境にデプロイする前に、必ずステージング環境でデプロイをテストしてください
• flyctl CLI を最新の状態に保ってください：flyctl version update
• Fly.io のステータスページでプラットフォームの障害を確認してください
• サポートやベストプラクティスに関する情報を得るため、Fly.io コミュニティに参加してください
• 本番環境のワークロードでは、Fly.io のマネージド PostgreSQL の利用を検討してください