# 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/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 ```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-.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 moi@exemple.fr --first Jean --last Dupont" make admin ARGS="--email moi@exemple.fr --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 | 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: credentials-file: /home//.cloudflared/.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`).