Skip to content

Commit ec76644

Browse files
tacxoutacxou
committed
update proxy doc
1 parent 74cf366 commit ec76644

4 files changed

Lines changed: 208 additions & 1 deletion

File tree

‎docs/.vuepress/config.js‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,8 @@ export default defineUserConfig({
2929
'installation-daemon',
3030
'installation-taiga',
3131
'gestion-mdp',
32-
'architecture-de-securite'
32+
'architecture-de-securite',
33+
'reverse-proxy-orchestrator'
3334
],
3435
},{
3536
text: 'Configuration',

‎docs/installation/architecture-de-securite.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,10 @@ Mettez vos certificats dans ./certificates
7272

7373
## Serveur orchestrator (Méthode par reverse proxy)
7474

75+
::: tip Configuration WebSocket (Socket.IO)
76+
Le frontal d'administration utilise Socket.IO sur `/api/socket.io` (temps réel : jobs, backends, cron). Le reverse-proxy doit supporter l'upgrade WebSocket et router **tout** le trafic vers le port Nuxt (`3000`), pas vers l'API (`4000`). Voir le guide détaillé : [Reverse-proxy — orchestrator](./reverse-proxy-orchestrator.md).
77+
:::
78+
7579
Un script est disponible pour l installation du reverse sur la machine docker hébergant l'orchestrator et le frontal de d'administration
7680
* créez un répertoire ex: "/data/revproxy" et allez dans ce répertoire
7781
* télécharger le script

‎docs/installation/installation-server.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,3 +109,10 @@ Vous pouvez vous connecter à l interface via http://votreserveur:3000
109109
```
110110
111111
L'etape suivante est l'installation des imports specifiques
112+
113+
## Exposition HTTPS (reverse-proxy)
114+
115+
Pour exposer l'interface en production derrière Nginx ou Apache (TLS, WebSocket Socket.IO, allowlist IP), consultez :
116+
117+
- [Reverse-proxy — orchestrator](./reverse-proxy-orchestrator.md)
118+
- [Architecture de sécurité](./architecture-de-securite.md)

‎docs/installation/reverse-proxy-orchestrator.md‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
# Reverse-proxy — frontal d'administration (orchestrator)
2+
3+
Ce guide s'adresse aux **administrateurs de site** qui exposent l'interface d'administration Sesame (Nuxt + API) derrière **Nginx** ou **Apache**.
4+
5+
## Principe
6+
7+
Depuis la version monolithique (`sesame-orchestrator`), le frontal web et l'API tournent dans **un seul conteneur** :
8+
9+
| Port interne | Service |
10+
| --- | --- |
11+
| `3000` | Frontal Nuxt (interface d'administration) |
12+
| `4000` | API NestJS (usage interne au conteneur) |
13+
14+
Le navigateur ne doit parler **qu'au port Nuxt** (`3000`). Nuxt proxifie ensuite les appels `/api/**` vers l'API interne (`SESAME_APP_API_URL`, par défaut `http://127.0.0.1:4000`).
15+
16+
| Chemin navigateur | Traitement |
17+
| --- | --- |
18+
| `/`, assets SPA | Nuxt |
19+
| `/api/**` (REST, authentification, etc.) | Nuxt → proxy interne → API |
20+
| `/api/socket.io` | Idem (long-polling HTTP **et** upgrade WebSocket) |
21+
22+
::: warning Ne pas exposer l'API directement
23+
Ne routez **pas** `/api` ou `/api/socket.io` vers le port `4000` depuis le reverse-proxy externe. Socket.IO et l'authentification par IP reposent sur le passage par Nuxt.
24+
:::
25+
26+
### Script d'installation automatique
27+
28+
Un script Nginx + Docker Compose est disponible pour une installation rapide (voir aussi [Architecture de sécurité](./architecture-de-securite.md#serveur-orchestrator-methode-par-reverse-proxy)) :
29+
30+
```bash
31+
mkdir -p /data/revproxy && cd /data/revproxy
32+
curl -L 'https://raw.githubusercontent.com/Libertech-FR/sesame-exemple/refs/heads/main/reverse_proxy/server/install.sh' --output install.sh
33+
bash install.sh
34+
docker compose up -d
35+
```
36+
37+
La section ci-dessous détaille la configuration manuelle, notamment pour **WebSocket** (Socket.IO temps réel : jobs, backends, cron).
38+
39+
---
40+
41+
## Variables d'environnement
42+
43+
| Variable | Fichier | Rôle |
44+
| --- | --- | --- |
45+
| `SESAME_APP_API_URL=http://127.0.0.1:4000` | `apps/web/.env` | Cible du proxy interne Nuxt → API |
46+
| `SESAME_TRUST_PROXY=1` | `apps/api/.env` | L'API lit `X-Forwarded-For` / `X-Real-IP` (allowlist IP à la connexion) |
47+
| `NUXT_PUBLIC_SOCKET_IO_POLLING_ONLY=false` | conteneur prod | Active WebSocket + repli polling (défaut en production) |
48+
49+
En production, **ne pas** définir `NUXT_PUBLIC_SOCKET_IO_POLLING_ONLY=true` : cela force le polling seul (mode développement).
50+
51+
---
52+
53+
## Nginx
54+
55+
### Configuration recommandée
56+
57+
Utiliser une `map` pour gérer correctement l'en-tête `Connection` lors des upgrades WebSocket :
58+
59+
```nginx
60+
map $http_upgrade $connection_upgrade {
61+
default upgrade;
62+
'' close;
63+
}
64+
65+
server {
66+
listen 443 ssl http2;
67+
server_name sesame.example.com;
68+
69+
# ssl_certificate ...
70+
# ssl_certificate_key ...
71+
72+
location / {
73+
proxy_pass http://sesame-orchestrator:3000;
74+
proxy_http_version 1.1;
75+
76+
# WebSocket (Socket.IO sur /api/socket.io)
77+
proxy_set_header Upgrade $http_upgrade;
78+
proxy_set_header Connection $connection_upgrade;
79+
80+
# IP client (allowlist API)
81+
proxy_set_header Host $host;
82+
proxy_set_header X-Real-IP $remote_addr;
83+
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
84+
proxy_set_header X-Forwarded-Proto $scheme;
85+
86+
proxy_read_timeout 86400;
87+
proxy_send_timeout 86400;
88+
}
89+
}
90+
```
91+
92+
Sur l'hôte (sans réseau Docker `reverse`), remplacer l'upstream par `http://127.0.0.1:3000` ou le port publié (ex. `3002`).
93+
94+
### Variante minimale
95+
96+
Équivalent des trois directives WebSocket courantes :
97+
98+
```nginx
99+
location / {
100+
proxy_pass http://sesame-orchestrator:3000;
101+
proxy_http_version 1.1;
102+
proxy_set_header Upgrade $http_upgrade;
103+
proxy_set_header Connection "upgrade";
104+
proxy_set_header Host $host;
105+
proxy_set_header X-Real-IP $remote_addr;
106+
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
107+
proxy_set_header X-Forwarded-Proto $scheme;
108+
}
109+
```
110+
111+
| Directive Nginx | Rôle |
112+
| --- | --- |
113+
| `proxy_http_version 1.1` | Requis pour l'upgrade WebSocket |
114+
| `proxy_set_header Upgrade $http_upgrade` | Transmet la demande d'upgrade du navigateur |
115+
| `proxy_set_header Connection "upgrade"` | Maintient le tunnel WebSocket vers Nuxt |
116+
117+
---
118+
119+
## Apache (2.4+)
120+
121+
### Modules requis
122+
123+
```apache
124+
LoadModule proxy_module modules/mod_proxy.so
125+
LoadModule proxy_http_module modules/mod_proxy_http.so
126+
LoadModule proxy_wstunnel_module modules/mod_proxy_wstunnel.so
127+
LoadModule rewrite_module modules/mod_rewrite.so
128+
LoadModule headers_module modules/mod_headers.so
129+
```
130+
131+
### VirtualHost avec upgrade WebSocket
132+
133+
```apache
134+
<VirtualHost *:443>
135+
ServerName sesame.example.com
136+
137+
SSLEngine on
138+
# SSLCertificateFile ...
139+
# SSLCertificateKeyFile ...
140+
141+
ProxyPreserveHost On
142+
RequestHeader set X-Forwarded-Proto "https"
143+
RequestHeader set X-Forwarded-For %{REMOTE_ADDR}s
144+
145+
# HTTP + WebSocket vers Nuxt (Socket.IO inclus dans /api/socket.io)
146+
RewriteEngine On
147+
RewriteCond %{HTTP:Upgrade} =websocket [NC]
148+
RewriteRule /(.*) ws://sesame-orchestrator:3000/$1 [P,L]
149+
RewriteCond %{HTTP:Upgrade} !=websocket [NC]
150+
RewriteRule /(.*) http://sesame-orchestrator:3000/$1 [P,L]
151+
152+
ProxyPassReverse / http://sesame-orchestrator:3000/
153+
</VirtualHost>
154+
```
155+
156+
Équivalent conceptuel des directives Nginx :
157+
158+
| Nginx | Apache |
159+
| --- | --- |
160+
| `proxy_http_version 1.1` | Règles `RewriteRule` vers `ws://` (WS) et `http://` (HTTP) |
161+
| `Upgrade` / `Connection` | Détection `%{HTTP:Upgrade} =websocket` |
162+
163+
Sur l'hôte sans réseau Docker, remplacer `sesame-orchestrator:3000` par `127.0.0.1:3000`.
164+
165+
---
166+
167+
## Docker Compose et réseau `reverse`
168+
169+
Avec le `docker-compose.prod.yml` officiel, le conteneur `sesame-orchestrator` expose le port `3000` sur le réseau Docker `reverse` (sans publication directe sur l'hôte).
170+
171+
Le reverse-proxy (Nginx ou Apache, souvent dans un conteneur dédié) doit :
172+
173+
1. Rejoindre le réseau externe `reverse` (`docker network create reverse`).
174+
2. Router **tout** le trafic HTTP et WebSocket vers `sesame-orchestrator:3000`.
175+
176+
---
177+
178+
## Vérification
179+
180+
Après mise en place :
181+
182+
1. **Socket.IO** : dans le panneau de debug de l'interface, le transport doit afficher `websocket` (ou `polling` en cas de repli).
183+
2. **IP client** : `GET /api/core/auth/client-ip` doit renvoyer l'adresse IP réelle du navigateur, et non `127.0.0.1`.
184+
3. **Connexion** : l'authentification par allowlist IP doit fonctionner derrière le proxy.
185+
186+
---
187+
188+
## Dépannage
189+
190+
| Symptôme | Cause probable | Action |
191+
| --- | --- | --- |
192+
| `Invalid frame header` (console navigateur) | Upgrade WebSocket non proxifié | Vérifier les directives WS ci-dessus |
193+
| Socket.IO reste en `polling` uniquement | Reverse-proxy sans support WS, ou `NUXT_PUBLIC_SOCKET_IO_POLLING_ONLY=true` | Corriger la config proxy / variables d'env |
194+
| Auth « IP non autorisée » avec `127.0.0.1` | `SESAME_TRUST_PROXY=0` ou en-têtes `X-Forwarded-For` absents | Activer `SESAME_TRUST_PROXY=1` et transmettre les en-têtes IP |
195+
| Fonctionne en local, échoue derrière le proxy | Config WebSocket manquante sur Nginx/Apache | Appliquer ce guide |

0 commit comments

Comments
 (0)