# OmniRoute Fly.io Deployment Guide (日本語)

🌐 **Languages:** 🇺🇸 [English](../../../../ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇪🇹 [am](../../../am/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇦🇿 [az](../../../az/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇧🇦 [bs](../../../bs/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇩🇰 [da](../../../da/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇩🇪 [de](../../../de/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇬🇷 [el](../../../el/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇪🇸 [es](../../../es/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇪🇪 [et](../../../et/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇱 [he](../../../he/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇩 [id](../../../id/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇹 [it](../../../it/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇰🇭 [km](../../../km/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇲🇲 [my](../../../my/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇳🇴 [no](../../../no/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [or](../../../or/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇱🇰 [si](../../../si/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇸🇰 [sk](../../../sk/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇰🇪 [sw](../../../sw/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [te](../../../te/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇹🇭 [th](../../../th/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md)

---

このドキュメントでは、OmniRoute を Fly.io に実際にデプロイする手順について、以下のシナリオを説明します。

- 現在のプロジェクトを初めて Fly.io にデプロイする
- 以降のコード更新を公開する
- 新しいプロジェクトで同じデプロイワークフローを使用する

このガイドは、現在のプロジェクトで動作確認済みの設定に基づいています。アプリケーション名は `omniroute` です。

---

## 1. デプロイの目標

- プラットフォーム: Fly.io
- デプロイ方法: ローカルの `flyctl` から直接公開
- ランタイム: リポジトリ内の既存の `Dockerfile` と `fly.toml` を使用
- データの永続化: `/data` にマウントされた Fly Volume
- アクセス URL: `https://omniroute.fly.dev/`

---

## 2. 現在のプロジェクトの主要設定

現在のリポジトリにある `fly.toml` に、以下の主要項目が含まれていることを確認済みです。

```toml
app = 'omniroute'
primary_region = 'sin'

[[mounts]]
  source = 'data'
  destination = '/data'

[processes]
  app = 'node run-standalone.mjs'

[http_service]
  internal_port = 20128

[env]
  TZ = "Asia/Shanghai"
  HOST = "0.0.0.0"
  HOSTNAME = "0.0.0.0"
  BIND = "0.0.0.0"
```

注意事項:

- `app = 'omniroute'` は、デプロイ対象となる Fly アプリケーションを指定します
- `destination = '/data'` は、永続ボリュームのマウント先ディレクトリを指定します
- このプロジェクトでは `DATA_DIR=/data` を設定する必要があります。設定しない場合、データベースとキーはコンテナの一時ディレクトリに書き込まれます

---

## 3. 前提条件

### 3.1 Fly CLI のインストール

Windows PowerShell:

```powershell
pwsh -Command "iwr https://fly.io/install.ps1 -useb | iex"
```

環境によってインストールスクリプトが失敗する場合は、`flyctl` バイナリを手動でダウンロードし、`PATH` に追加することもできます。

### 3.2 Fly アカウントへのログイン

```powershell
flyctl auth login
```

### 3.3 ログイン状態の確認

```powershell
flyctl auth whoami
flyctl version
```

---

## 4. 現在のプロジェクトを初めてデプロイする

### 4.1 コードをクローンしてディレクトリに移動する

```powershell
git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute
```

### 4.2 アプリケーション名を確認する

`fly.toml` を開き、以下の行を確認します。

```toml
app = 'omniroute'
```

独自の新しいアプリケーションにデプロイする場合は、グローバルに一意な名前へ変更できます。例:

```toml
app = 'omniroute-yourname'
```

注意:

- コンソールに表示されるアプリケーションが、`fly.toml` の `app` の値と一致していることを確認してください
- 以前に `oroute` など別の名前を使用していた場合は、`omniroute` と混同しないでください

### 4.3 アプリケーションを作成する

アプリケーションがまだ存在しない場合:

```powershell
flyctl apps create omniroute
```

アプリケーション名を変更した場合は、`omniroute` を選択した名前に置き換えてください。

### 4.4 初回デプロイ

```powershell
flyctl deploy
```

---

## 5. 必須パラメーター

このプロジェクトでは、Fly.io に少なくとも以下のパラメーターを設定することを推奨します。

### 5.1 検証済みパラメーター

以下のパラメーターは、現在の `omniroute` アプリケーションへの実際のデプロイで使用されています。

- `API_KEY_SECRET`
- `DATA_DIR`
- `JWT_SECRET`
- `MACHINE_ID_SALT`
- `NEXT_PUBLIC_BASE_URL`
- `OMNIROUTE_WS_BRIDGE_SECRET`（本番環境では必須 — WebSocket ブリッジ認証に使用）
- `STORAGE_ENCRYPTION_KEY`

### 5.2 `INITIAL_PASSWORD` について

現在のプロジェクトでは、このデプロイに必要ないため `INITIAL_PASSWORD` を設定していません。

設定しない場合:

- 起動ログに、デフォルトパスワードが `CHANGEME` であることが表示されます
- デプロイ後、できるだけ早くシステム設定でログインパスワードを変更してください

バックエンドのパスワードを無人で初期化したい場合は、後から以下を追加できます。

- `INITIAL_PASSWORD`

---

## 6. 推奨パラメータ

### 6.1 シークレットの設定

Fly Secrets には、以下の変数を設定することを推奨します。

| 変数                         | 推奨度           | 説明                                             |
| ---------------------------- | ---------------- | ------------------------------------------------ |
| `API_KEY_SECRET`             | 必須             | API キーの生成と検証に使用                       |
| `JWT_SECRET`                 | 必須             | ログインセッションと JWT 署名に使用              |
| `OMNIROUTE_WS_BRIDGE_SECRET` | 本番環境では必須 | WebSocket ブリッジの認証シークレット             |
| `STORAGE_ENCRYPTION_KEY`     | 強く推奨         | 保存されている機密性の高い接続情報を暗号化       |
| `MACHINE_ID_SALT`            | 推奨             | 安定したマシン識別子を生成                       |
| `INITIAL_PASSWORD`           | 任意             | 初回デプロイ時の初期バックエンドパスワードを設定 |
| OAuth/API の非公開認証情報   | 必要に応じて     | 外部プラットフォームの認証設定                   |

### 6.2 現在のプロジェクトの推奨値

| 変数                   | 推奨値                      |
| ---------------------- | --------------------------- |
| `DATA_DIR`             | `/data`                     |
| `NEXT_PUBLIC_BASE_URL` | `https://omniroute.fly.dev` |

注意事項:

- `DATA_DIR=/data` は非常に重要であり、Fly Volume のマウントポイントと一致している必要があります
- `NEXT_PUBLIC_BASE_URL` は、スケジューラー、フロントエンドのコールバック、および同様の用途で使用されます

### 6.3 OAuth コールバック URL の設定

Fly.io へのデプロイで OAuth ベースのプロバイダー（例: Antigravity、Gemini、Cursor）を有効にする必要がある場合は、以下の 2 点を確認してください。

1. **`NEXT_PUBLIC_BASE_URL` を公開 HTTPS ドメインに設定する**

   ```powershell
   flyctl secrets set NEXT_PUBLIC_BASE_URL=https://omniroute.fly.dev -a omniroute
   ```

   カスタムドメインを使用している場合は、対応するドメイン（例: `https://omniroute.yourdomain.com`）に置き換えてください。

2. **プロバイダーのコンソールでコールバック URL を設定する**

   すべての OAuth プロバイダーは、単一のコールバックパス `/callback` を共有します。プロバイダーごとのコールバックルートはありません。

   ```text
   <NEXT_PUBLIC_BASE_URL>/callback
   ```

   たとえば、Gemini、Antigravity、Cursor、GitLab Duo のいずれでも、以下を使用します。
   - `https://omniroute.fly.dev/callback`

   `NEXT_PUBLIC_BASE_URL` がプロバイダーに登録されたコールバック URL と一致しない場合、OAuth フローはブラウザのリダイレクト手順で失敗します。

---

## 7. 1 コマンドでのシークレット設定

以下のコマンドは、安全なランダム値を生成し、現在のプロジェクトに必要なすべてのパラメータを 1 回の操作で Fly Secrets に書き込みます。

注意事項:

- `INITIAL_PASSWORD` は含まれません
- 現在のプロジェクト `omniroute` を対象としています

```powershell
$apiKeySecret = [Convert]::ToHexString((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })).ToLower()
$jwtSecret = [Convert]::ToHexString((1..64 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })).ToLower()
$machineIdSalt = [Convert]::ToHexString((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })).ToLower()
$storageKey = [Convert]::ToHexString((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })).ToLower()
$wsBridgeSecret = [Convert]::ToHexString((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })).ToLower()

flyctl secrets set `
  API_KEY_SECRET=$apiKeySecret `
  JWT_SECRET=$jwtSecret `
  MACHINE_ID_SALT=$machineIdSalt `
  STORAGE_ENCRYPTION_KEY=$storageKey `
  OMNIROUTE_WS_BRIDGE_SECRET=$wsBridgeSecret `
  DATA_DIR=/data `
  NEXT_PUBLIC_BASE_URL=https://omniroute.fly.dev `
  -a omniroute
```

Linux / macOS では、`openssl rand -hex 32` も使用できます。

```bash
flyctl secrets set OMNIROUTE_WS_BRIDGE_SECRET=$(openssl rand -hex 32) -a omniroute
```

注意事項:

- `OMNIROUTE_WS_BRIDGE_SECRET` は本番環境では必須です。設定されていない場合、WebSocket ブリッジのハンドシェイクが失敗します

初期パスワードも設定する場合:

```powershell
flyctl secrets set INITIAL_PASSWORD=your-strong-password -a omniroute
```

---

## 8. 現在のパラメータの確認

```powershell
flyctl secrets list -a omniroute
```

コンソールの `Secrets` ページに想定される変数が表示されない場合は、以下を確認してください。

- `omniroute` アプリケーションを表示していること
- `fly.toml` の `app` の値が、コンソール上のアプリケーションと一致していること

---

## 9. 以降の更新とリリース

コードを更新した後のリリース手順は簡単です。

```powershell
git pull
flyctl deploy
```

コードを変更せず、パラメータのみを更新する場合は、以下を実行します。

```powershell
flyctl secrets set KEY=value -a omniroute
```

Fly はマシンのローリングアップデートを自動的に実行します。

### 9.1 フォークの `fly.toml` を維持しながらアップストリームリポジトリの更新を取り込む

現在のリポジトリがフォークであり、アップストリームの `https://github.com/diegosouzapw/OmniRoute` から更新を同期する場合は、以下のワークフローに従ってください。

まず、リモートを確認します。

```powershell
git remote -v
```

少なくとも以下が表示される必要があります。

- 自分のフォークを指す `origin`
- 元のリポジトリを指す `upstream`

`upstream` が設定されていない場合は、追加します。

```powershell
git remote add upstream https://github.com/diegosouzapw/OmniRoute.git
```

アップストリームと同期する前に、最新のコミットとタグを取得します。

```powershell
git fetch upstream --tags
```

現在のバージョンとアップストリームのタグを確認します。

```powershell
git describe --tags --always
git show --no-patch --oneline v3.4.7
```

> 注: 現在のプロジェクトバージョンは `v3.8.0` です。以下の `v3.4.7` への参照は、過去の例としてのみ残されています。実際のリリースでは、`:latest` または現在のバージョンタグ（例: `:v3.8.0`）を使用してください。

フォークの `fly.toml` を強制的に維持しながら、アップストリームの最新の `main` をマージする場合は、以下のワークフローに従ってください。

```powershell
git merge upstream/main
git checkout HEAD~1 -- fly.toml
git add -- fly.toml
git commit -m "chore(deploy): keep fork fly.toml"
git push origin main
```

注:

- `git merge upstream/main` は、元のリポジトリから最新のコードを同期します
- `git checkout HEAD~1 -- fly.toml` は、マージ前のフォーク独自の `fly.toml` を復元します
- アップストリームで `fly.toml` が変更されていない場合、この手順によって差分が発生することはありません
- アップストリームで `fly.toml` が変更されていた場合、この手順により、Fly アプリケーション名、ボリュームマウント、リージョン、およびその他のフォーク固有のデプロイ設定が上書きされるのを防げます

特定のリリースタグ（例: `v3.4.7`）に合わせる場合は、まずそのタグがすでに `upstream/main` に含まれていることを確認します。

```powershell
git merge-base --is-ancestor v3.4.7 upstream/main
```

正常に終了した場合、`upstream/main` にはそのバージョンがすでに含まれています。そのまま `upstream/main` をマージできます。

### 9.2 アップストリーム同期後の標準リリース手順

元のリポジトリと同期した後は、以下の推奨順序でリリースしてください。

1. `git fetch upstream --tags`
2. `git merge upstream/main`
3. フォークの `fly.toml` を復元する
4. `git push origin main`
5. `flyctl deploy`
6. `flyctl status -a omniroute`
7. `flyctl logs --no-tail -a omniroute`

これは、現在のプロジェクトを `v3.4.7` にアップグレードした際に実際に使用されたワークフローです（この例は過去のバージョンを示しており、現在の実際のバージョンは `v3.8.0` です）。

---

## 10. デプロイ後の確認

### 10.1 アプリケーションのステータスを確認する

```powershell
flyctl status -a omniroute
```

### 10.2 起動ログを表示する

```powershell
flyctl logs --no-tail -a omniroute
```

### 10.3 サイトにアクセスできることを確認する

```powershell
try {
  (Invoke-WebRequest -Uri "https://omniroute.fly.dev" -MaximumRedirection 5 -UseBasicParsing).StatusCode
} catch {
  if ($_.Exception.Response) {
    $_.Exception.Response.StatusCode.value__
  } else {
    throw
  }
}
```

戻り値が `200` であれば、サイトが正常に応答していることを示します。

---

## 11. 成功を示す指標

デプロイが成功すると、ログには次のような内容が表示されます。

```text
[bootstrap] Secrets persisted to: /data/server.env
[DB] SQLite database ready: /data/storage.sqlite
```

次の2点が重要です。

- `/data/server.env` は、実行時のシークレットが永続ボリュームに書き込まれていることを示します
- `/data/storage.sqlite` は、データベースが永続ボリュームに書き込まれていることを示します

代わりに `/app/data/...` が表示される場合は、`DATA_DIR` の設定に誤りがあるため、直ちに修正する必要があります。

---

## 12. よくある問題

### 12.1 `Secrets` ページが空である

通常、次の2つの原因が考えられます。

- まだ `flyctl secrets set` を実行していない
- 別のアプリケーションを表示している（例：`omniroute` ではなく `oroute`）

### 12.2 `flyctl deploy` で `app not found` と表示される

最初にアプリケーションを作成してください。

```powershell
flyctl apps create omniroute
```

### 12.3 `fly.toml` の解析に失敗する

次の点を確認してください。

- コメントに文字化けがないか
- TOML の引用符とインデントが正しいか

### 12.4 データが永続化されない

次の両方を確認してください。

- `fly.toml` に `destination = '/data'` が含まれている
- `DATA_DIR` が `/data` に設定されている

### 12.5 `INITIAL_PASSWORD` なしでも実行できるか？

はい、実行できます。デフォルトのパスワード `CHANGEME` にフォールバックします。本番環境では、バックエンドのパスワードをできるだけ早く変更することを推奨します。

---

## 13. 新しいプロジェクトでの再利用

このドキュメントに従って新しいプロジェクトをデプロイする場合は、次の項目のみを変更する必要があります。

1. `fly.toml` の `app` の値を変更する
2. `NEXT_PUBLIC_BASE_URL` を変更する
3. `DATA_DIR=/data` はそのまま維持する
4. `API_KEY_SECRET`、`JWT_SECRET`、`MACHINE_ID_SALT`、`STORAGE_ENCRYPTION_KEY` を再生成する
5. 初回デプロイ後、ログが `/data` に書き込まれていることを確認する

以前のプロジェクトのキーを再利用しないでください。

---

## 14. 現在のプロジェクト向け最小リリースチェックリスト

以降のリリースで最もよく使用するコマンドは次のとおりです。

```powershell
flyctl auth whoami
flyctl status -a omniroute
flyctl secrets list -a omniroute
flyctl deploy
flyctl logs --no-tail -a omniroute
```

通常のリリースでは、中心となるコマンドは次の1つだけです。

```powershell
flyctl deploy
```

新しい環境への初回デプロイでは、主な手順は次のとおりです。

1. `flyctl auth login`
2. `flyctl apps create omniroute`
3. `flyctl secrets set ... -a omniroute`
4. `flyctl deploy`
5. `flyctl logs --no-tail -a omniroute`