chore: initial import of CoHaiSe Cloud
PR — Ouverture automatique / create-pr (push) Failing after 1s
PR — Ouverture automatique / create-pr (push) Failing after 1s
Standalone files & media application: React/Vite frontend with the @cohaise/ui design system, Hono + MariaDB backend, nginx reverse proxy, Docker Compose stack, migrations 000-006, and project docs. Adds Gitea Actions workflows for deployment, automatic pull requests, and Renovate dependency updates.
This commit is contained in:
@@ -0,0 +1,191 @@
|
||||
# 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/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_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, volume `db_data` |
|
||||
| `migrate` | — | — | joue les migrations manquantes, puis s'arrête |
|
||||
| `api` | `3101` | `GET :8080/healthz` (start 20 s) | Hono, volume `media_data` |
|
||||
| `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.
|
||||
|
||||
> **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 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 :
|
||||
|
||||
```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é.
|
||||
- `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` :
|
||||
|
||||
```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 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`).
|
||||
Reference in New Issue
Block a user