# OmniRoute Fly.io Deployment Guide (Français)

🌐 **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) · 🇮🇪 [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) · 🇯🇵 [ja](../../../ja/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)

---

Ce document décrit le processus de déploiement réel d’OmniRoute sur Fly.io, couvrant trois scénarios :

- Déployer le projet actuel sur Fly.io pour la première fois
- Publier les mises à jour ultérieures du code
- Déployer de nouveaux projets en suivant le même processus de déploiement

Ce guide repose sur une configuration vérifiée et fonctionnelle pour le projet actuel. Le nom de l’application est `omniroute`.

---

## 1. Objectifs du déploiement

- Plateforme : Fly.io
- Méthode de déploiement : publication directe locale avec `flyctl`
- Environnement d’exécution : utilisation des fichiers `Dockerfile` et `fly.toml` existants dans le dépôt
- Persistance des données : volume Fly monté sur `/data`
- URL d’accès : `https://omniroute.fly.dev/`

---

## 2. Configuration principale du projet actuel

Il a été confirmé que le fichier `fly.toml` du dépôt actuel contient les éléments principaux suivants :

```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"
```

Remarques :

- `app = 'omniroute'` détermine l’application Fly ciblée par le déploiement
- `destination = '/data'` détermine le répertoire de montage du volume persistant
- Ce projet doit définir `DATA_DIR=/data`, sinon la base de données et les clés seront écrites dans le répertoire temporaire du conteneur

---

## 3. Prérequis

### 3.1 Installation de l’interface de ligne de commande Fly

Windows PowerShell :

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

Si le script d’installation échoue dans votre environnement, vous pouvez également télécharger manuellement le binaire `flyctl` et l’ajouter à votre `PATH`.

### 3.2 Connexion à votre compte Fly

```powershell
flyctl auth login
```

### 3.3 Vérification de l’état de la connexion

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

---

## 4. Premier déploiement du projet actuel

### 4.1 Cloner le code et accéder au répertoire

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

### 4.2 Confirmer le nom de l’application

Ouvrez `fly.toml` et vérifiez la ligne suivante :

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

Si vous effectuez le déploiement vers votre propre nouvelle application, vous pouvez remplacer ce nom par un nom unique à l’échelle mondiale, par exemple :

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

Remarque :

- Assurez-vous que l’application affichée dans la console correspond à la valeur `app` du fichier `fly.toml`
- Si vous avez précédemment utilisé un autre nom, tel que `oroute`, ne le confondez pas avec `omniroute`

### 4.3 Créer l’application

Si l’application n’existe pas encore :

```powershell
flyctl apps create omniroute
```

Si vous avez modifié le nom de l’application, remplacez `omniroute` par le nom que vous avez choisi.

### 4.4 Premier déploiement

```powershell
flyctl deploy
```

---

## 5. Paramètres requis

Pour ce projet, il est recommandé de configurer au minimum les paramètres suivants sur Fly.io.

### 5.1 Paramètres vérifiés

Ces paramètres ont été utilisés lors de déploiements réels de l’application `omniroute` actuelle :

- `API_KEY_SECRET`
- `DATA_DIR`
- `JWT_SECRET`
- `MACHINE_ID_SALT`
- `NEXT_PUBLIC_BASE_URL`
- `OMNIROUTE_WS_BRIDGE_SECRET` (requis en production — utilisé pour l’authentification du pont WebSocket)
- `STORAGE_ENCRYPTION_KEY`

### 5.2 À propos de `INITIAL_PASSWORD`

Le projet actuel ne définit pas `INITIAL_PASSWORD`, car ce déploiement ne le nécessite pas.

S’il n’est pas défini :

- Le journal de démarrage indiquera que le mot de passe par défaut est `CHANGEME`
- Vous devez modifier le mot de passe de connexion dans les paramètres système dès que possible après le déploiement

Si vous souhaitez initialiser le mot de passe du backend sans intervention, vous pouvez l’ajouter ultérieurement :

- `INITIAL_PASSWORD`

---

## 6. Paramètres recommandés

### 6.1 Configuration des secrets

Les variables suivantes sont recommandées pour Fly Secrets :

| Variable                      | Recommandation            | Description                                                            |
| ----------------------------- | ------------------------- | ---------------------------------------------------------------------- |
| `API_KEY_SECRET`              | Obligatoire               | Utilisée pour la génération et la validation des clés API              |
| `JWT_SECRET`                  | Obligatoire               | Utilisée pour les sessions de connexion et la signature des JWT        |
| `OMNIROUTE_WS_BRIDGE_SECRET`  | Obligatoire en production | Secret d’authentification de la passerelle WebSocket                   |
| `STORAGE_ENCRYPTION_KEY`      | Fortement recommandée     | Chiffre au repos les informations de connexion sensibles               |
| `MACHINE_ID_SALT`             | Recommandée               | Génère un identifiant de machine stable                                |
| `INITIAL_PASSWORD`            | Facultative               | Définit le mot de passe initial du backend lors du premier déploiement |
| Identifiants privés OAuth/API | Selon les besoins         | Configuration de l’authentification auprès de plateformes externes     |

### 6.2 Valeurs recommandées pour le projet actuel

| Variable               | Valeur recommandée          |
| ---------------------- | --------------------------- |
| `DATA_DIR`             | `/data`                     |
| `NEXT_PUBLIC_BASE_URL` | `https://omniroute.fly.dev` |

Remarques :

- `DATA_DIR=/data` est essentiel et doit correspondre au point de montage du volume Fly
- `NEXT_PUBLIC_BASE_URL` est utilisée par le planificateur, les rappels du frontend et dans des scénarios similaires

### 6.3 Configuration de l’URL de rappel OAuth

Si vous devez activer des fournisseurs basés sur OAuth (par exemple Antigravity, Gemini, Cursor) sur le déploiement Fly.io, assurez-vous de respecter les deux points suivants :

1. **Définissez `NEXT_PUBLIC_BASE_URL` sur votre domaine HTTPS public**

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

   Si vous utilisez un domaine personnalisé, remplacez-la par le domaine correspondant (par exemple `https://omniroute.yourdomain.com`).

2. **Configurez l’URL de rappel dans la console du fournisseur**

   Tous les fournisseurs OAuth partagent l’unique chemin de rappel `/callback` — il n’existe AUCUNE route de rappel propre à chaque fournisseur :

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

   Par exemple, qu’il s’agisse de Gemini, Antigravity, Cursor ou GitLab Duo :
   - `https://omniroute.fly.dev/callback`

   Si `NEXT_PUBLIC_BASE_URL` ne correspond pas à l’URL de rappel enregistrée auprès du fournisseur, le flux OAuth échouera lors de l’étape de redirection du navigateur.

---

## 7. Configuration des secrets en une seule commande

Les commandes suivantes génèrent des valeurs aléatoires sécurisées et écrivent en une seule étape dans Fly Secrets tous les paramètres requis pour le projet actuel.

Remarques :

- N’inclut pas `INITIAL_PASSWORD`
- Destiné au projet actuel `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
```

Sous Linux / macOS, vous pouvez également utiliser `openssl rand -hex 32` :

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

Remarques :

- `OMNIROUTE_WS_BRIDGE_SECRET` est obligatoire en production ; son absence empêchera l’établissement de la connexion avec la passerelle WebSocket

Si vous souhaitez également définir un mot de passe initial :

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

---

## 8. Affichage des paramètres actuels

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

Si la page `Secrets` de la console n'affiche pas les variables attendues, vérifiez :

- Que vous consultez l'application `omniroute`
- Que la valeur `app` dans `fly.toml` correspond à l'application dans la console

---

## 9. Mises à jour et déploiements ultérieurs

Après une mise à jour du code, le processus de déploiement est simple :

```powershell
git pull
flyctl deploy
```

Si vous devez uniquement mettre à jour les paramètres sans modifier le code :

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

Fly effectuera automatiquement une mise à jour progressive des machines.

### 9.1 Suivi des mises à jour du dépôt en amont tout en préservant le fichier `fly.toml` de votre fork

Si le dépôt actuel est un fork et que vous souhaitez synchroniser les mises à jour depuis le dépôt en amont `https://github.com/diegosouzapw/OmniRoute`, suivez la procédure ci-dessous.

Commencez par vérifier vos dépôts distants :

```powershell
git remote -v
```

Vous devriez voir au moins :

- `origin` pointant vers votre propre fork
- `upstream` pointant vers le dépôt d'origine

Si `upstream` n'est pas configuré, ajoutez-le :

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

Avant d'effectuer la synchronisation avec le dépôt en amont, récupérez les derniers commits et tags :

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

Vérifiez la version actuelle et les tags du dépôt en amont :

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

> Remarque : la version actuelle du projet est `v3.8.0`. Les références à `v3.4.7` ci-dessous sont conservées uniquement comme exemples historiques. Pour les versions réelles, utilisez `:latest` ou le tag de la version actuelle (par exemple `:v3.8.0`).

Si vous souhaitez fusionner la dernière version de la branche `main` du dépôt en amont tout en conservant de force le fichier `fly.toml` de votre fork, suivez cette procédure :

```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
```

Remarques :

- `git merge upstream/main` synchronise le code le plus récent depuis le dépôt d'origine
- `git checkout HEAD~1 -- fly.toml` restaure le fichier `fly.toml` propre à votre fork depuis l'état antérieur à la fusion
- Si le dépôt en amont n'a pas modifié `fly.toml`, cette étape n'introduira aucune différence
- Si le dépôt en amont a modifié `fly.toml`, cette étape garantit que le nom de votre application Fly, le montage du volume, la région et les autres paramètres de déploiement propres à votre fork ne seront pas écrasés

Si vous souhaitez vous aligner sur un tag de version spécifique (par exemple `v3.4.7`), vérifiez d'abord que le tag est déjà inclus dans `upstream/main` :

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

Un retour réussi signifie que `upstream/main` contient déjà cette version ; vous pouvez simplement fusionner `upstream/main`.

### 9.2 Séquence de déploiement standard après la synchronisation avec le dépôt en amont

Après la synchronisation avec le dépôt d'origine, suivez cet ordre de déploiement recommandé :

1. `git fetch upstream --tags`
2. `git merge upstream/main`
3. Restaurer le fichier `fly.toml` du fork
4. `git push origin main`
5. `flyctl deploy`
6. `flyctl status -a omniroute`
7. `flyctl logs --no-tail -a omniroute`

Il s'agit de la procédure réellement utilisée lors de la mise à niveau du projet actuel vers `v3.4.7` (l'exemple fait référence à une version historique ; la version actuelle réelle est `v3.8.0`).

---

## 10. Vérifications après le déploiement

### 10.1 Vérifier l’état de l’application

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

### 10.2 Consulter les journaux de démarrage

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

### 10.3 Vérifier l’accessibilité du site

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

Une valeur de retour de `200` indique que le site répond normalement.

---

## 11. Indicateurs de réussite

Après un déploiement réussi, les journaux devraient afficher un contenu similaire à celui-ci :

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

Ces deux points sont essentiels :

- `/data/server.env` confirme que les secrets d’exécution sont écrits sur le volume persistant
- `/data/storage.sqlite` confirme que la base de données est écrite sur le volume persistant

Si `/app/data/...` apparaît à la place, `DATA_DIR` est mal configuré et doit être corrigé immédiatement.

---

## 12. Problèmes courants

### 12.1 La page `Secrets` est vide

Il y a généralement deux raisons :

- Vous n’avez pas encore exécuté `flyctl secrets set`
- Vous consultez une autre application (par exemple, `oroute` au lieu de `omniroute`)

### 12.2 `flyctl deploy` signale `app not found`

Créez d’abord l’application :

```powershell
flyctl apps create omniroute
```

### 12.3 Échec de l’analyse de `fly.toml`

Vérifiez les points suivants :

- La présence éventuelle de caractères illisibles dans les commentaires
- L’exactitude des guillemets et de l’indentation TOML

### 12.4 Les données ne sont pas conservées

Vérifiez les deux points suivants :

- `fly.toml` contient `destination = '/data'`
- `DATA_DIR` est défini sur `/data`

### 12.5 L’application peut-elle fonctionner sans `INITIAL_PASSWORD` ?

Oui, elle peut fonctionner. Elle utilisera alors le mot de passe par défaut `CHANGEME`. Il est recommandé de modifier le mot de passe du backend dès que possible en production.

---

## 13. Réutilisation pour de nouveaux projets

Si vous déployez un nouveau projet en suivant ce document, il vous suffit de modifier les éléments suivants :

1. Modifiez la valeur `app` dans `fly.toml`
2. Modifiez `NEXT_PUBLIC_BASE_URL`
3. Conservez `DATA_DIR=/data`
4. Régénérez `API_KEY_SECRET`, `JWT_SECRET`, `MACHINE_ID_SALT` et `STORAGE_ENCRYPTION_KEY`
5. Après le premier déploiement, vérifiez que les journaux sont écrits dans `/data`

Ne réutilisez pas les clés d’un projet précédent.

---

## 14. Liste de contrôle minimale pour les versions du projet actuel

Les commandes les plus couramment utilisées pour les versions ultérieures sont :

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

Pour une version normale, la commande principale est simplement :

```powershell
flyctl deploy
```

Pour un premier déploiement dans un nouvel environnement, les étapes principales sont :

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`