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