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.
11 KiB
Déploiement — CoHaiSe Cloud
Démarrer
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_HOSTetSMTP_FROMsont 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 (
../dbet../mediapar défaut, réglables parCLOUD_DB_DIR/CLOUD_MEDIA_DIR). Ils vivent donc hors de/var/lib/docker, sur le gros disque. Seulapp_data(sortie de build du front) reste un volume Docker. Undocker compose down -vne 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 dedocker/nginx/exige de reconstruire le servicenginx. L'API embarquesharp(binaires précompilés musl attendus sur Alpine) ; vérifier le démarrage après un changement de base.
Commandes
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é dansschema_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 :
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
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
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 surCOHAISE_HTTP_PORT(8083 par défaut) avecserver_name _: n'importe quelHostest 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_ORIGINne sert qu'à un front servi depuis une autre origine ; avec un tunnel unique, laisser vide.- Garder
TRUST_PROXY=true: l'API lit alorsX-Forwarded-For/-Protoposé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 valeurclient_max_body_size 5gde 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 :
# 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_headerdansdocker/nginx/cloud.conf). Sans cela,limit_reqet 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 :
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.ymllit le secretDEPLOY_DIR; s'il n'est pas défini, la valeur par défaut/srv/apps/cohaise-cloud/CoHaiSe-CLOUDest utilisée. Créer le secretDEPLOY_DIRune 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.ymlutilise leGITHUB_TOKENfourni par Gitea Actions. Si les PR sont refusées, créer un secretPAT(jeton personnel Gitea, portéerepo) et remplacersecrets.GITHUB_TOKEN.renovate.ymlexigeRENOVATE_TOKEN: jeton personnel Gitea avec la portéerepo.
python3doit ê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).