Files
CoHaiSe-CLOUD/docs/deployment.md
T
Esiah a22f18d860
CD — Déploiement / deploy (push) Failing after 1s
chore: store database and media on host bind mounts
Move MariaDB and media data out of /var/lib/docker onto the host disk via CLOUD_DB_DIR and CLOUD_MEDIA_DIR (default ../db, ../media). Only the frontend build output remains a named volume.
2026-10-16 10:47:12 +02:00

8.6 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/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

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 :
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é.
  • cloudflared publie le service local (http://127.0.0.1:8083).
  • 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.
  • Les cookies de session passent en Secure dès que le proxy annonce X-Forwarded-Proto: https (cloudflared le fait) : garder TRUST_PROXY=true.
  • Certificat et HSTS sont assurés en amont par Cloudflare — ne pas exposer directement le port 8083 sur Internet.

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