OmniRoute — Deployment Guide on VM with Cloudflare (Français)

Prérequis

Élément	Minimum	Recommandé
CPU	1 vCPU	2 vCPU
RAM	1 Go	2 Go
Disque	SSD de 10 Go	SSD de 25 Go
OS	Ubuntu 22.04 LTS	Ubuntu 24.04 LTS
Domaine	Enregistré sur Cloudflare	—
Docker	Docker Engine 24+	Docker 27+

Fournisseurs testés : Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail.

---

1. Configurer la VM

1.1 Créer l’instance

Chez votre fournisseur de VPS préféré :

• Choisissez Ubuntu 24.04 LTS
• Sélectionnez l’offre minimale (1 vCPU / 1 Go de RAM)
• Définissez un mot de passe root robuste ou configurez une clé SSH
• Notez l’adresse IP publique (par exemple, 203.0.113.10)

1.2 Se connecter via SSH

ssh root@203.0.113.10

1.3 Mettre à jour le système

apt update && apt upgrade -y

1.4 Installer Docker

# Installer les dépendances
apt install -y ca-certificates curl gnupg

# Ajouter le dépôt Docker officiel
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
chmod a+r /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $ (. /etc/os-release && echo "$VERSION_CODENAME") stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null
apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

1.5 Installer nginx

apt install -y nginx

1.6 Configurer le pare-feu (UFW)

ufw default deny incoming
ufw default allow outgoing
ufw allow 22/tcp    # SSH
ufw allow 80/tcp    # HTTP (redirection)
ufw allow 443/tcp   # HTTPS
ufw enable

Conseil : Pour une sécurité maximale, limitez les ports 80 et 443 aux adresses IP de Cloudflare uniquement. Consultez la section Sécurité avancée.

---

2. Installer OmniRoute

2.1 Créer le répertoire de configuration

mkdir -p /opt/omniroute

2.2 Créer le fichier des variables d’environnement

cat > /opt/omniroute/.env << 'EOF'
# === Sécurité ===
JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY
INITIAL_PASSWORD=YourSecurePassword123!
API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY
STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY
STORAGE_ENCRYPTION_KEY_VERSION=v1
MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT
OMNIROUTE_WS_BRIDGE_SECRET=REPLACE-WITH-WS-BRIDGE-SECRET  # OBLIGATOIRE en production : utilisé par le pont WS de Codex Responses

# === Application ===
PORT=20128
NODE_ENV=production
HOSTNAME=0.0.0.0
DATA_DIR=/app/data
APP_LOG_TO_FILE=true
AUTH_COOKIE_SECURE=true
REQUIRE_API_KEY=false

# === URL (à remplacer par votre domaine) ===
# URL de base interne de serveur à serveur pour les tâches planifiées et les requêtes vers le serveur lui-même.
BASE_URL=http://127.0.0.1:20128
# URL destinée au navigateur, utilisée pour les rappels OAuth, les liens du tableau de bord et les URL publiques générées.
NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com
# Remplacement explicite facultatif de l’origine publique pour les URL générées des ressources publiques.
# OMNIROUTE_PUBLIC_BASE_URL=https://llms.seudominio.com

# === Synchronisation cloud (facultative) ===
# CLOUD_URL=https://cloud.omniroute.online
# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online
EOF

⚠️ IMPORTANT : Générez des clés secrètes uniques ! Utilisez openssl rand -hex 32 pour chaque clé.

2.3 Démarrer le conteneur

docker pull diegosouzapw/omniroute:latest

docker run -d \
  --name omniroute \
  --restart unless-stopped \
  --env-file /opt/omniroute/.env \
  -p 20128:20128 \
  -v omniroute-data:/app/data \
  diegosouzapw/omniroute:latest

2.4 Vérifier qu’il est en cours d’exécution

docker ps | grep omniroute
docker logs omniroute --tail 20

La sortie devrait afficher : [DB] SQLite database ready et listening on port 20128.

---

3. Configurer nginx (proxy inverse)

3.1 Générer un certificat SSL (Cloudflare Origin)

Dans le tableau de bord Cloudflare :

1. Accédez à SSL/TLS → Origin Server
2. Cliquez sur Create Certificate
3. Conservez les valeurs par défaut (15 ans, *.yourdomain.com)
4. Copiez l’Origin Certificate et la Private Key

mkdir -p /etc/nginx/ssl

# Collez le certificat
nano /etc/nginx/ssl/origin.crt

# Collez la clé privée
nano /etc/nginx/ssl/origin.key

chmod 600 /etc/nginx/ssl/origin.key

3.2 Configuration de nginx

cat > /etc/nginx/sites-available/omniroute << 'NGINX'
# Serveur par défaut — bloque l’accès direct via l’adresse IP
server {
    listen 80 default_server;
    listen [::]:80 default_server;
    listen 443 ssl default_server;
    listen [::]:443 ssl default_server;
    ssl_certificate     /etc/nginx/ssl/origin.crt;
    ssl_certificate_key /etc/nginx/ssl/origin.key;
    server_name _;
    return 444;
}

# OmniRoute — HTTPS
server {
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name llms.yourdomain.com;  # Remplacez par votre domaine

    ssl_certificate     /etc/nginx/ssl/origin.crt;
    ssl_certificate_key /etc/nginx/ssl/origin.key;
    ssl_protocols TLSv1.2 TLSv1.3;

    client_max_body_size 100M;

    location / {
        proxy_pass http://127.0.0.1:20128;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Prise en charge de WebSocket
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # SSE (Server-Sent Events) — diffusion en continu des réponses de l’IA
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 600s;
        proxy_send_timeout 600s;
    }
}

# Redirection HTTP → HTTPS
server {
    listen 80;
    listen [::]:80;
    server_name llms.yourdomain.com;
    return 301 https://$server_name$request_uri;
}
NGINX

Maintenez les délais d’expiration des flux du proxy inverse alignés sur les variables d’environnement de délai d’expiration d’OmniRoute. Si vous augmentez FETCH_TIMEOUT_MS / STREAM_IDLE_TIMEOUT_MS, augmentez proxy_read_timeout / proxy_send_timeout au-dessus du même seuil.

OmniRoute utilise NEXT_PUBLIC_BASE_URL comme origine canonique visible par le navigateur pour les rappels OAuth et les liens publics générés. Les écritures authentifiées du tableau de bord utilisent des requêtes de même origine ainsi qu’une protection CSRF liée à la session ; elles ne nécessitent donc pas d’URL de base publique statique. Les en-têtes X-Forwarded-* ci-dessus restent des métadonnées de routage utiles, mais ils ne remplacent pas la définition explicite de l’URL publique lorsque OAuth ou les liens générés pour le navigateur en ont besoin. N’activez OMNIROUTE_TRUST_PROXY que si OmniRoute n’est pas directement accessible par les clients et que votre proxy supprime/reconstruit les en-têtes transférés entrants.

3.3 Activer et tester

# Supprimez la configuration par défaut
rm -f /etc/nginx/sites-enabled/default

# Activez OmniRoute
ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute

# Testez et rechargez
nginx -t && systemctl reload nginx

---

4. Configurer le DNS Cloudflare

4.1 Ajouter un enregistrement DNS

Dans le tableau de bord Cloudflare → DNS :

Type	Nom	Contenu	Proxy
A	llms	203.0.113.10 (IP de la VM)	✅ Activé

4.2 Configurer SSL

Sous SSL/TLS → Vue d’ensemble :

• Mode : Complet (strict)

Sous SSL/TLS → Certificats de périphérie :

• Toujours utiliser HTTPS : ✅ Activé
• Version TLS minimale : TLS 1.2
• Réécritures HTTPS automatiques : ✅ Activées

4.3 Test

curl -sI https://llms.seudominio.com/health
# Doit renvoyer HTTP/2 200

---

5. Exploitation et maintenance

Mettre à niveau vers une nouvelle version

docker pull diegosouzapw/omniroute:latest
docker stop omniroute && docker rm omniroute
docker run -d --name omniroute --restart unless-stopped \
  --env-file /opt/omniroute/.env \
  -p 20128:20128 \
  -v omniroute-data:/app/data \
  diegosouzapw/omniroute:latest

Consulter les journaux

docker logs -f omniroute          # Flux en temps réel
docker logs omniroute --tail 50   # 50 dernières lignes

Sauvegarde manuelle de la base de données

# Copier les données du volume vers l’hôte
docker cp omniroute:/app/data ./backup-$(date +%F)

# Ou compresser l’intégralité du volume
docker run --rm -v omniroute-data:/data -v $(pwd):/backup \
  alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data

Restaurer à partir d’une sauvegarde

docker stop omniroute
docker run --rm -v omniroute-data:/data -v $(pwd):/backup \
  alpine sh -c "rm -rf /data/* && tar xzf /backup/omniroute-data-YYYY-MM-DD.tar.gz -C /"
docker start omniroute

---

6. Sécurité avancée

Restreindre nginx aux adresses IP de Cloudflare

cat > /etc/nginx/cloudflare-ips.conf << 'CF'
# Plages IPv4 de Cloudflare — à mettre à jour régulièrement
# https://www.cloudflare.com/ips-v4/
set_real_ip_from 173.245.48.0/20;
set_real_ip_from 103.21.244.0/22;
set_real_ip_from 103.22.200.0/22;
set_real_ip_from 103.31.4.0/22;
set_real_ip_from 141.101.64.0/18;
set_real_ip_from 108.162.192.0/18;
set_real_ip_from 190.93.240.0/20;
set_real_ip_from 188.114.96.0/20;
set_real_ip_from 197.234.240.0/22;
set_real_ip_from 198.41.128.0/17;
set_real_ip_from 162.158.0.0/15;
set_real_ip_from 104.16.0.0/13;
set_real_ip_from 104.24.0.0/14;
set_real_ip_from 172.64.0.0/13;
set_real_ip_from 131.0.72.0/22;
real_ip_header CF-Connecting-IP;
CF

Ajoutez la ligne suivante à nginx.conf dans le bloc http {} :

include /etc/nginx/cloudflare-ips.conf;

Installer fail2ban

apt install -y fail2ban
systemctl enable fail2ban
systemctl start fail2ban

# Vérifier l’état
fail2ban-client status sshd

Bloquer l’accès direct au port Docker

# Empêcher l’accès externe direct au port 20128
iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP
iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT

# Rendre les règles persistantes
apt install -y iptables-persistent
netfilter-persistent save

---

7. Déployer sur Cloudflare Workers (facultatif)

Pour un accès à distance via Cloudflare Workers (sans exposer directement la VM) :

# Dans le dépôt local
cd omnirouteCloud
npm install
npx wrangler login
npx wrangler deploy

Consultez également TUNNELS_GUIDE.md pour obtenir le guide pas à pas du tunnel Cloudflare inclus dans le dépôt. Le worker autonome omnirouteCloud/ se trouve dans un dépôt complémentaire distinct.

---

Résumé des ports

Port	Service	Accès
22	SSH	Public (avec fail2ban)
80	nginx HTTP	Redirection → HTTPS
443	nginx HTTPS	Via le proxy Cloudflare
20128	OmniRoute	Localhost uniquement (via nginx)

Optimisation pour les petits VPS / à faible mémoire

Pour les déploiements sur de petites instances VPS (1 Go de RAM ou moins) :

• Désactiver les services en arrière-plan — définissez OMNIROUTE_DISABLE_BACKGROUND_SERVICES=1 pour ignorer le planificateur, le serveur MCP et les tâches de maintenance périodiques. Consultez docs/reference/ENVIRONMENT.md.
• Utiliser le mode WAL de SQLite — activé par défaut, il réduit le pic d’utilisation de la mémoire lors des lectures simultanées.
• Limiter le tas V8 — définissez OMNIROUTE_MEMORY_MB (par ex. 512) afin que l’environnement d’exécution ne calibre pas une limite supérieure à celle de la VM. Consultez docs/reference/ENVIRONMENT.md.
• Le contrôle d’admission des requêtes lourdes s’adapte automatiquement à la limite du tas – une fois OMNIROUTE_MEMORY_MB défini comme indiqué ci-dessus, le budget d’octets d’ingestion (OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES) est calculé à partir de cette même limite. Ainsi, une VM à mémoire limitée bénéficie déjà d’un budget réduit pour les requêtes simultanées sans réglage supplémentaire ; les requêtes excédentaires reçoivent une réponse 503 permettant une nouvelle tentative, avec Retry-After, au lieu d’entrer en concurrence pour la mémoire. Définissez l’ancienne limite du nombre de requêtes OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT uniquement si vous avez besoin d’un plafond strict supplémentaire.
• Éviter next build sur le VPS — effectuez la compilation localement et déployez la sortie autonome (.next/standalone/).
• Surveiller avec top / free -m — OmniRoute utilise généralement entre 200 et 400 Mo de mémoire RSS au repos sur une VM de 1 Go.

---

Code source d’OmniRoute (a58000c7685f)