Files
CoHaiSe-CLOUD/docs/deployment.md
T
Esiah 93c6942cd5
PR — Ouverture automatique / create-pr (push) Successful in 3s
feat(ui): glass layout, icon actions and new icon set
2026-11-03 23:31:25 +01:00

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/lib/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., 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

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 :
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 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 :

# 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 :

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).