d56fb7d3d4
SERVICE_FQDN_* gets regenerated with a random hash on each Coolify save, making custom domains impossible to persist. Introduce APP_URL as a single user-controlled variable (never auto-generated) for all app URLs. Derive VITE_BACKEND_WS_URL automatically from VITE_BASE_URL in aio_run.mjs so only APP_URL needs to be set. SERVICE_FQDN_HOPPSCOTCH_80 is kept solely for Coolify proxy routing. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
243 lines
4.8 KiB
Markdown
243 lines
4.8 KiB
Markdown
# Hoppscotch Self-Hosted
|
|
|
|
Fork interne de Hoppscotch pour déploiement self-host.
|
|
|
|
## Contenu
|
|
|
|
- App web : `packages/hoppscotch-selfhost-web`
|
|
- Backend NestJS et Prisma : `packages/hoppscotch-backend`
|
|
- 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`
|
|
|
|
## Images Docker
|
|
|
|
Les images sont buildées en local puis poussées à la main sur le registry.
|
|
|
|
Image utilisée en prod :
|
|
|
|
```text
|
|
forge.lclr.dev/thibaud-lclr/api-client-aio:latest
|
|
```
|
|
|
|
Targets Docker :
|
|
|
|
```text
|
|
backend -> backend + Caddy backend
|
|
app -> app web + webapp-server + Caddy app
|
|
sh_admin -> admin + Caddy admin
|
|
aio -> app, admin, backend et webapp-server derrière un Caddy unique
|
|
```
|
|
|
|
## Préparer l'environnement
|
|
|
|
Créer `.env` si besoin :
|
|
|
|
```sh
|
|
make ensure-env
|
|
```
|
|
|
|
Variables importantes pour le compose dev :
|
|
|
|
```env
|
|
POSTGRES_PASSWORD=<mot-de-passe-fort>
|
|
POSTGRES_DB=hoppscotch
|
|
DATA_ENCRYPTION_KEY=<chaine-de-32-caracteres>
|
|
|
|
VITE_BASE_URL=https://<domaine-app>
|
|
VITE_SHORTCODE_BASE_URL=https://<domaine-app>
|
|
VITE_ADMIN_URL=https://<domaine-admin>
|
|
VITE_BACKEND_GQL_URL=https://<domaine-backend>/graphql
|
|
VITE_BACKEND_WS_URL=wss://<domaine-backend>/graphql
|
|
VITE_BACKEND_API_URL=https://<domaine-backend>/v1
|
|
|
|
WHITELISTED_ORIGINS=https://<domaine-app>,https://<domaine-admin>
|
|
TRUST_PROXY=true
|
|
```
|
|
|
|
Pour le compose prod local, ces variables pilotent les images :
|
|
|
|
```env
|
|
API_CLIENT_REGISTRY=forge.lclr.dev
|
|
API_CLIENT_NAMESPACE=thibaud-lclr
|
|
API_CLIENT_IMAGE_PREFIX=api-client
|
|
API_CLIENT_TAG=latest
|
|
```
|
|
|
|
Le compose prod local utilise aussi les valeurs `SERVICE_*` présentes dans
|
|
`.env.example`. En production Coolify, ces valeurs sont générées par Coolify à
|
|
partir de `docker-compose.prod.yml`.
|
|
|
|
## Build et push registry
|
|
|
|
Se connecter au registry :
|
|
|
|
```sh
|
|
docker login forge.lclr.dev
|
|
```
|
|
|
|
Builder l'image prod en `latest` :
|
|
|
|
```sh
|
|
make docker-build-images TAG=latest
|
|
```
|
|
|
|
Pousser l'image prod :
|
|
|
|
```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.
|
|
|
|
Sur Coolify, `docker-compose.prod.yml` est la source de vérité des variables
|
|
d'environnement. Les variables sont déclarées dans les blocs `environment:` pour
|
|
que Coolify les crée dans son UI au chargement du compose. Il ne faut pas
|
|
compter sur un fichier `.env` du dépôt en prod : il est ignoré par Git.
|
|
|
|
Le compose prod utilise l'image AIO et un seul domaine Coolify :
|
|
|
|
- `/` : app web
|
|
- `/admin` : admin
|
|
- `/backend` : backend GraphQL/API
|
|
|
|
Variables à configurer dans Coolify :
|
|
|
|
- `APP_URL` : URL publique du service (ex: `https://hoppscotch.mondomaine.fr`). À renseigner une fois manuellement — jamais écrasée par Coolify. L'URL WebSocket est dérivée automatiquement au démarrage.
|
|
- `SERVICE_PASSWORD_POSTGRES` : mot de passe PostgreSQL généré par Coolify
|
|
- `SERVICE_BASE64_HOPPSCOTCH` : clé stable de 32 caractères pour `DATA_ENCRYPTION_KEY`, générée par Coolify
|
|
|
|
`SERVICE_FQDN_HOPPSCOTCH_80` est géré par Coolify pour la configuration du proxy — sa valeur n'affecte pas l'app, seul `APP_URL` compte.
|
|
|
|
Les URLs app/admin/backend sont dérivées de `APP_URL` par sous-chemins.
|
|
|
|
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
|
|
make prod-logs
|
|
```
|
|
|
|
Voir l'état des services :
|
|
|
|
```sh
|
|
make prod-ps
|
|
```
|
|
|
|
Arrêter :
|
|
|
|
```sh
|
|
make prod-down
|
|
```
|
|
|
|
Services prod :
|
|
|
|
- `hoppscotch-db` : PostgreSQL 15 avec volume persistant
|
|
- `hoppscotch` : app web, admin, backend, serveur de bundles et migrations Prisma au démarrage
|
|
|
|
Routage prod :
|
|
|
|
- `/` : app web
|
|
- `/admin` : admin
|
|
- `/backend` : backend
|
|
|
|
## 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
|
|
```
|