Files
CoHaiSe-CLOUD/docs/deployment.md
T
Esiah 23df7dd7c6
PR — Ouverture automatique / create-pr (push) Successful in 2s
fix(nginx): join shared-network and read real client IP via CF-Connecting-IP
- nginx rejoint le reseau externe shared-network pour que le tunnel
  Cloudflare le resolue par son nom (cohaise-cloud-nginx).
- real_ip_header CF-Connecting-IP :  devient l'IP reelle du
  client, sinon limit_req et l'audit comptent l'IP du tunnel.
- X-Forwarded-Proto reprend le schema vu par Cloudflare (https) au lieu de
  $scheme (http) : le cookie de session repasse en Secure.
- docs/deployment.md : tunnel Docker via shared-network, deploy.yml sans make check.
2026-10-16 11:18:18 +02:00

224 lines
9.5 KiB
Markdown

# Déploiement — CoHaiSe Cloud
## Démarrer
```sh
cp .env.example .env # renseigner mots de passe + SESSION_SECRET (≥ 32 car.)
make up # db → migrate → api → nginx, front compris
make front # reconstruire et republier le front
```
Réponse sur **`http://localhost:8083`**.
La configuration est validée **avant** l'ouverture d'aucun port : si une variable
manque ou est mal formée, le process s'arrête en listant exactement ce qui
pose problème (`backend/shared/src/config.ts`).
## Variables
| Variable | Rôle | Défaut |
| --- | --- | --- |
| `COHAISE_HTTP_PORT` | port nginx | `8083` |
| `COHAISE_API_PORT` | port API | `3101` |
| `COHAISE_DB_PORT` | port MariaDB | `3407` |
| `CLOUD_DATABASE` / `CLOUD_DB_USER` / `CLOUD_DB_PASSWORD` | base applicative | — |
| `CLOUD_DB_ROOT_PASSWORD` | root, réservé aux sauvegardes | — |
| `CLOUD_DB_DIR` | dossier hôte des données MariaDB | `../db` |
| `CLOUD_MEDIA_DIR` | dossier hôte des médias | `../media` |
| `CLOUD_DB_CONNECTION_LIMIT` | taille du pool | `8` |
| `SESSION_SECRET` | **obligatoire**, ≥ 32 car. | — |
| `SESSION_TTL_HOURS` | durée de session | `336` |
| `PUBLIC_ORIGIN` | **obligatoire**, URL absolue servant aux liens courriel | — |
| `CLOUD_CORS_ORIGIN` | origines CORS (vide = CORS off) | vide |
| `SMTP_HOST` | **obligatoire**, relais d'envoi | — |
| `SMTP_PORT` | port SMTP | `587` |
| `SMTP_USER` / `SMTP_PASSWORD` | authentification (vides = relais local) | vide |
| `SMTP_FROM` | adresse d'expédition | — |
| `SMTP_SECURE` | TLS implicite (port 465) | `false` |
| `RATE_LIMIT_LOGIN_MAX` | tentatives par fenêtre | `10` |
| `RATE_LIMIT_LOGIN_WINDOW_MS` | largeur de fenêtre | `60000` |
| `LOG_LEVEL` | `silent…debug` | `info` |
| `TRUST_PROXY` | croire `X-Forwarded-*` | `true` |
> `PUBLIC_ORIGIN`, `SMTP_HOST` et `SMTP_FROM` sont **obligatoires** : sans eux
> l'API refuse de démarrer (courriel de réinitialisation / confirmation).
Variables fixes posées par compose : `PORT=8080`, `DB_HOST=db`,
`MEDIA_DIR=/data/media/originals`, `VARIANT_DIR=/data/media/variants`,
`NODE_ENV=production`, `TZ=Europe/Paris`.
> **Écueil** : si une clé attendue manque dans `.env`, compose utilise
> silencieusement son **défaut**. En cas de doute, comparer avec `.env.example` :
> c'est la référence, pas `.env`.
## Services
| Service | Port | Santé | Rôle |
| --- | --- | --- | --- |
| `db` | `3407` | `healthcheck.sh --connect --innodb_initialized` | MariaDB, bind mount `$CLOUD_DB_DIR` |
| `migrate` | — | — | joue les migrations manquantes, puis s'arrête |
| `api` | `3101` | `GET :8080/healthz` (start 20 s) | Hono, bind mount `$CLOUD_MEDIA_DIR` |
| `nginx` | `8083` | `GET /healthz` | sert le front, proxy `/api/` |
| `app-build` | — | — | build + publication atomique, `restart: "no"` |
Ordre garanti par `depends_on` : `migrate` attend `db` healthy, `api` attend
`db` healthy **et** `migrate` terminé avec succès.
> **Données** : la base et les médias sont des **bind mounts** vers l'hôte
> (`../db` et `../media` par défaut, réglables par `CLOUD_DB_DIR` /
> `CLOUD_MEDIA_DIR`). Ils vivent donc hors de `/var/lib/docker`, sur le gros
> disque. Seul `app_data` (sortie de build du front) reste un volume Docker.
> Un `docker compose down -v` ne supprime donc **pas** la base ni les médias.
> **Images** : la configuration nginx (CSP/HSTS, `limit_req`, snippets) est
> **copiée dans l'image**. Toute modification de `docker/nginx/` exige de
> reconstruire le service `nginx`. L'API embarque `sharp` (binaires précompilés
> musl attendus sur Alpine) ; vérifier le démarrage après un changement de base.
## Commandes
```sh
make help # liste complète
make ps / make logs # état et journaux
make front # reconstruire + republier le front
make db # redémarrer la base
make migrate # rejouer explicitement les migrations (hors démarrage)
make backup # dump horodaté → ./backups/cloud-<stamp>.sql.gz
make admin ARGS=... # créer / réinitialiser un compte
make dev # Vite 5174, proxy /api → 3101
make check # typecheck + build
make down # arrêt, volumes conservés
```
`make backup` lit le mot de passe **dans le conteneur** : il ne passe ni par la
commande, ni par le dépôt.
## Migrations
- Fichiers `NNN_nom.sql`, tri lexical, appliqués une seule fois, checksum
SHA-256 enregistré dans `schema_migrations`.
- **Une migration appliquée ne se modifie jamais** : une correction passe par
un nouveau numéro. Si le contenu d'un fichier déjà joué change,
`assertNoDrift()` refuse le démarrage de l'API.
- Application automatique au démarrage, ou manuelle :
```sh
make migrate
docker compose run --rm migrate node dist/cli.js --dir /migrations --dry-run
docker compose run --rm migrate node dist/cli.js --dir /migrations --check # 1 s'il en reste
```
Codes de sortie : `0` OK, `1` erreur ou dérive, `2` configuration.
## Comptes
```sh
make admin ARGS="--email [email protected] --first Jean --last Dupont"
make admin ARGS="--email [email protected] --reset"
```
Options : `--email` (obligatoire), `--first`/`--last` (obligatoires à la
création), `--role` (défaut `admin`), `--password`, `--reset`. Sans
`--password`, le mot de passe est généré (18 caractères) et affiché **une
seule fois**. Un compte créé a `must_change_password=1`.
Aucune route HTTP ne crée un compte.
## Sauvegarde et restauration
```sh
make backup # dump compressé dans ./backups/
```
Le dossier `backups/` est gitignoré. Pour restaurer : `gunzip -c <dump> | make
… ` via un conteneur `db` en service — opération manuelle, à faire hors
démarrage automatique.
## Exposition — Cloudflare Tunnel
L'application est prête à être publiée derrière un tunnel Cloudflare : aucune
adresse ni aucun domaine n'est codé en dur.
- `nginx` écoute sur `COHAISE_HTTP_PORT` (8083 par défaut) avec `server_name _` :
n'importe quel `Host` est accepté.
- Renseigner l'origine publique **exacte** vue par les navigateurs :
`PUBLIC_ORIGIN=https://cloud.example.com`. Elle sert aux liens envoyés par
courriel (réinitialisation, confirmation).
- `CLOUD_CORS_ORIGIN` ne sert qu'à un front servi depuis une autre origine ;
avec un tunnel unique, laisser vide.
- Garder `TRUST_PROXY=true` : l'API lit alors `X-Forwarded-For`/`-Proto` posés
par nginx. Sans lui, tous les clients partageraient l'IP du proxy (limitation
de connexion globale, audit inutile).
- Certificat et HSTS sont assurés en amont par Cloudflare — ne pas exposer
directement le port 8083 sur Internet.
**Tunnel Docker sur un réseau partagé (recommandé).** On joint nginx au réseau
du tunnel plutôt que de publier un port : `cloudflared` résout `nginx` par nom,
comme les autres applications de l'hôte :
```yaml
# docker-compose.yml
services:
nginx:
networks: [default, shared-network]
networks:
shared-network:
external: true
```
Côté Cloudflare (Tunnel → Public Hostname) : sous-domaine/domaine, Type `HTTP`,
URL `http://cohaise-cloud-nginx:80`. Le réseau doit déjà exister
(`docker network ls`) — il est créé par le compose du tunnel.
> nginx lit l'IP réelle du client dans `CF-Connecting-IP`
> (`real_ip_header` dans `docker/nginx/cloud.conf`). Sans cela, `limit_req` et
> l'audit compteraient l'IP du conteneur du tunnel, commune à tous.
**Variante : tunnel sur l'hôte.** Si `cloudflared` tourne directement sur la
machine (hors réseau Docker), il publie `http://127.0.0.1:8083` :
`shared-network` est alors inutile. Exemple `~/.cloudflared/config.yml` :
```yaml
tunnel: <id-tunnel>
credentials-file: /home/<utilisateur>/.cloudflared/<id-tunnel>.json
ingress:
- hostname: cloud.example.com
service: http://127.0.0.1:8083
- service: http_status:404
```
Les ports `8083`, `3101` et `3407` sont publiés sur **127.0.0.1 uniquement** :
rien n'est joignable depuis l'extérieur en dehors du tunnel.
## Intégration continue (Gitea Actions)
Le dépôt vit sur Gitea. **Gitea Actions** reprend la syntaxe GitHub Actions,
mais exige sur l'instance : un **runner self-hosted** enregistré
(Administration → Actions → Runners) et les **Actions activées** sur le dépôt
(Paramètres du dépôt → section Actions/Unités).
| Workflow | Déclencheur | Rôle |
| --- | --- | --- |
| `deploy.yml` | push `main` (backend/frontend/docker) ou manuel | `git pull`, `make front`, rebuild `api`+`nginx` |
| `pr.yml` | push hors `main` | ouvre une PR vers `main` via l'API REST Gitea (`curl` + `python3`) |
| `renovate.yml` | hebdomadaire ou manuel | lance Renovate contre Gitea |
À adapter avant activation :
- **Chemin de déploiement** : `deploy.yml` lit le secret `DEPLOY_DIR` ; s'il
n'est pas défini, la valeur par défaut `/srv/apps/cohaise-cloud/CoHaiSe-CLOUD`
est utilisée. Créer le secret `DEPLOY_DIR` une fois le chemin réel connu.
- **Label du runner** : `runs-on: self-hosted` ; si le runner porte des labels
additionnels (ex. `gitea`, `docker`), les renseigner.
- **Secrets** (Paramètres → Actions → Secrets) :
- `pr.yml` utilise le `GITHUB_TOKEN` fourni par Gitea Actions. Si les PR sont
refusées, créer un secret `PAT` (jeton personnel Gitea, portée `repo`) et
remplacer `secrets.GITHUB_TOKEN`.
- `renovate.yml` exige `RENOVATE_TOKEN` : jeton personnel Gitea avec la portée
`repo`.
- `python3` doit être présent sur le runner (Debian l'a par défaut).
**dependabot.yml n'est pas supporté par Gitea** : Renovate le remplace, avec
`renovate.json` (groupes npm backend/frontend, images Docker) et le workflow
`renovate.yml` (image `ghcr.io/renovatebot/renovate` en `RENOVATE_PLATFORM=gitea`).