Files
CoHaiSe-CLOUD/docs/deployment.md
T
Esiah 68d4d5dea0
PR — Ouverture automatique / create-pr (push) Successful in 3s
refactor: restructure frontend and backend by domain services
Split the monolithic backend (lib/, routes/, access.ts, storage.ts, media.ts)
into a layered structure inspired by JeanXXIII-CRM:
- config/: appConfig, db
- middleware/: auth (session, roles, cookies)
- models/: shared types
- routes/: *Routes.ts (thin HTTP handlers)
- services/: *Service.ts (business logic, one per domain)
- utils/: errors, http, migrate, ratelimit, validators, service bootstrap

Frontend likewise: services/*Service.ts + apiClient, contexts/, types/, utils/format.
Route files now carry the "Routes" suffix; service files are named
authService.ts, ratelimit.ts, etc. and live in their own files, frontend and
backend separated.

Updated docs and READMEs to reflect the new layout. Typecheck and builds pass.
2026-11-13 09:45:21 +01:00

255 lines
11 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/src/config/appConfig.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., poivre HMAC des jetons de session | — |
| `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` |
| `MAIL_LOGO_URL` | logo distant des courriels (sinon logo embarqué `backend/src/assets/logo.png`) | vide |
| `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 purge-logs # vider le journal d'audit
make reset # cloud vierge, administrateurs conservés (confirmation)
make dev # Vite 5174, proxy /api → 3101
make check # typecheck + build
make down # arrêt, volumes conservés
```
`make backup`, `make purge-logs` et `make reset` lisent le mot de passe **dans
le conteneur** : il ne passe ni par la commande, ni par le dépôt.
## Maintenance
### Vider les journaux
`make purge-logs` supprime le contenu de `audit_logs` (table
`docker/reset-cloud.sql` mise à part). Les comptes, fichiers et dossiers sont
intacts.
### Remettre le cloud à zéro
`make reset` repart d'une instance vierge **en conservant les comptes
administrateurs** :
- supprime fichiers, dossiers, partages, permissions, avatars, sessions, jetons
(réinitialisation, changement d'adresse) et journaux d'audit ;
- supprime tous les comptes **sauf** ceux dont le rôle est `admin` ;
- remet `storage_locations.used_bytes` à zéro ;
- efface les médias sur disque (`$CLOUD_MEDIA_DIR`), originaux, vignettes et
avatars compris.
La commande demande une confirmation (`o`/`y`). Enchaîner `make backup` avant
si l'état doit être conservé.
## 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.
- **Corps de requête** : Cloudflare plafonne le corps à 100 MB (Free/Pro). Les
fichiers plus gros passent par l'envoi resumable (`/api/cloud/uploads`) en
morceaux de 50 MiB, sans relever la limite de corps de nginx ni exposer
l'origine. La valeur `client_max_body_size 5g` de nginx ne concerne que le
chemin direct local.
**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`).