From 09347b9193df3c4dce876fb3e4f32c08d41dba8b Mon Sep 17 00:00:00 2001 From: thibaud-leclere Date: Wed, 6 May 2026 15:13:48 +0200 Subject: [PATCH] docs: update deployment workflow --- README.md | 216 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 180 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 17c0e990..40a08d4e 100644 --- a/README.md +++ b/README.md @@ -1,78 +1,222 @@ -# Hoppscotch AIO +# Hoppscotch Self-Hosted -Fork interne de Hoppscotch réduit au déploiement self-host all-in-one pour -Coolify. +Fork interne de Hoppscotch pour déploiement self-host. -## Contenu conservé +## Contenu -- Application web self-host : `packages/hoppscotch-selfhost-web` +- App web : `packages/hoppscotch-selfhost-web` - Backend NestJS et Prisma : `packages/hoppscotch-backend` -- Admin self-host : `packages/hoppscotch-sh-admin` -- Packages partagés requis au build : `hoppscotch-common`, `hoppscotch-data`, - `hoppscotch-kernel`, `hoppscotch-js-sandbox`, `codemirror-lang-graphql` -- Image Docker de production : `prod.Dockerfile` -- Déploiement Compose AIO : `docker-compose.yml` +- Admin : `packages/hoppscotch-sh-admin` +- Image Docker multi-target : `prod.Dockerfile` +- Compose dev live : `docker-compose.yml` +- Compose prod image-only : `docker-compose.prod.yml` -## Déploiement Coolify +## Images Docker -Utiliser `docker-compose.yml` comme source Compose. +Les images sont buildées en local puis poussées à la main sur le registry. -Services créés : +Images utilisées en prod : -- `hoppscotch-aio` : image AIO construite depuis `prod.Dockerfile`, target - `aio` -- `hoppscotch-db` : PostgreSQL 15 avec volume persistant +```text +forge.lclr.dev/thibaud-lclr/api-client-backend:latest +forge.lclr.dev/thibaud-lclr/api-client-app:latest +forge.lclr.dev/thibaud-lclr/api-client-sh-admin:latest +``` -Ports exposés : +Targets Docker : -- `3080` -> Caddy AIO HTTP -- `3000` -> app web -- `3100` -> admin -- `3170` -> backend -- `3200` -> serveur de bundles webapp +```text +backend -> backend + Caddy backend +app -> app web + webapp-server + Caddy app +sh_admin -> admin + Caddy admin +``` -Variables minimales à vérifier dans Coolify : +## Préparer l'environnement + +Créer `.env` si besoin : + +```sh +make ensure-env +``` + +Variables importantes : ```env POSTGRES_PASSWORD= POSTGRES_DB=hoppscotch DATA_ENCRYPTION_KEY= + VITE_BASE_URL=https:// VITE_SHORTCODE_BASE_URL=https:// VITE_ADMIN_URL=https:// VITE_BACKEND_GQL_URL=https:///graphql VITE_BACKEND_WS_URL=wss:///graphql VITE_BACKEND_API_URL=https:///v1 + WHITELISTED_ORIGINS=https://,https:// TRUST_PROXY=true ``` -`DATABASE_URL` est généré par `docker-compose.yml` pour la base PostgreSQL -incluse. Si le déploiement passe plus tard sur une base externe, adapter -explicitement le service `hoppscotch-aio`. +Pour le compose prod local, ces variables pilotent les images : -## Local - -Créer le fichier `.env` si nécessaire : - -```sh -cp .env.example .env +```env +API_CLIENT_REGISTRY=forge.lclr.dev +API_CLIENT_NAMESPACE=thibaud-lclr +API_CLIENT_IMAGE_PREFIX=api-client +API_CLIENT_TAG=latest ``` -Démarrer l'AIO local : +## Build et push registry + +Se connecter au registry : ```sh -docker compose up -d --build +docker login forge.lclr.dev +``` + +Builder les trois images en `latest` : + +```sh +make docker-build-images TAG=latest +``` + +Pousser les trois images : + +```sh +make docker-push-images TAG=latest +``` + +Faire les deux en une commande : + +```sh +make docker-build-push-images TAG=latest +``` + +Pour publier un tag de test : + +```sh +make docker-build-push-images TAG=fork-v1.0.0 +``` + +## Déploiement prod + +La prod utilise uniquement `docker-compose.prod.yml`. + +Ce compose ne contient pas de `build:`. Il tire les images du registry. + +Démarrer avec le tag `latest` : + +```sh +make prod-up +``` + +Démarrer avec un autre tag : + +```sh +make prod-up TAG=fork-v1.0.0 ``` Voir les logs : ```sh -docker compose logs -f +make prod-logs +``` + +Voir l'état des services : + +```sh +make prod-ps ``` Arrêter : ```sh -docker compose down +make prod-down +``` + +Services prod : + +- `hoppscotch-db` : PostgreSQL 15 avec volume persistant +- `hoppscotch-backend` : backend + migrations Prisma au démarrage +- `hoppscotch-app` : app web self-host +- `hoppscotch-sh-admin` : admin + +Ports prod : + +- `3000` : app web +- `3100` : admin +- `3170` : backend +- `3200` : serveur de bundles webapp + +## Développement local + +Le compose dev est `docker-compose.yml`. + +Il build une image de base locale et monte le repo en volume. + +Démarrer : + +```sh +make dev-up +``` + +Alias : + +```sh +make up +``` + +Voir les logs : + +```sh +make dev-logs +``` + +Voir l'état : + +```sh +make dev-ps +``` + +Arrêter : + +```sh +make dev-down +``` + +Services dev : + +- `hoppscotch-db` +- `hoppscotch-dev-deps` : installe les dépendances dans un volume Docker +- `hoppscotch-backend` : `pnpm run start:dev` +- `hoppscotch-app` : Vite sur `3000` +- `hoppscotch-sh-admin` : Vite sur `3100` + +Volumes dev : + +- le repo est monté dans `/usr/src/app` +- `node_modules` est dans un volume Docker +- le store pnpm est dans un volume Docker + +## Procédure de release courte + +1. Mettre à jour le code. +2. Vérifier localement. +3. Builder et pousser : + +```sh +make docker-build-push-images TAG=latest +``` + +4. Déployer : + +```sh +make prod-up +``` + +5. Contrôler : + +```sh +make prod-ps +make prod-logs ```