CD — Déploiement / deploy (push) Failing after 25s
- logo embarque dans les e-mails (CID) et gabarit repense en mode sombre - favicon multi-tailles + icone PNG, logo a gauche du titre (app et auth) - modale de confirmation animee a la place de window.confirm - bouton retour et fil d'ariane dans l'explorateur --------- Co-authored-by: xEsiah <[email protected]> Reviewed-on: #4 Reviewed-by: Esiah <[email protected]> Co-authored-by: Gitea Actions <-[email protected]>
250 lines
11 KiB
Markdown
250 lines
11 KiB
Markdown
# 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. | — |
|
|
| `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-<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 :
|
|
|
|
```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 [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
|
|
|
|
```sh
|
|
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.
|
|
|
|
**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: <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`).
|