PR — Ouverture automatique / create-pr (push) Successful in 3s
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.
255 lines
11 KiB
Markdown
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`).
|