thibaud-lclr/api-client
1
0
Fork 0
Code Packages Activity Actions
api-client/README.md
thibaud-leclere 8e8b715962 fix: revert to Coolify native SERVICE_FQDN_* variables for domain management 
COOLIFY_URL/COOLIFY_FQDN were custom variables requiring manual setup,
causing VITE_BACKEND_WS_URL to resolve to wss://backend/graphql (broken).
SERVICE_FQDN_HOPPSCOTCH_80 triggers Coolify auto-generation of an editable
domain, and SERVICE_URL_HOPPSCOTCH provides the scheme-less form needed for
the wss:// WebSocket URL.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-11 14:48:08 +00:00

4.9 KiB
Raw Blame History

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 :

forge.lclr.dev/thibaud-lclr/api-client-aio:latest

Targets Docker :

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 :

make ensure-env

Variables importantes pour le compose dev :

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 :

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 :

docker login forge.lclr.dev

Builder l'image prod en latest :

make docker-build-images TAG=latest

Pousser l'image prod :

make docker-push-images TAG=latest

Faire les deux en une commande :

make docker-build-push-images TAG=latest

Pour publier un tag de test :

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 auto-générées par Coolify (éditables dans l'UI) :

  • SERVICE_FQDN_HOPPSCOTCH_80 : déclenche la génération du domaine public et la configuration du proxy
  • SERVICE_FQDN_HOPPSCOTCH : URL publique avec schéma (https://api-xxx.host.fr)
  • SERVICE_URL_HOPPSCOTCH : domaine sans schéma, utilisé pour l'URL WebSocket (wss://)
  • SERVICE_PASSWORD_POSTGRES : mot de passe PostgreSQL généré
  • SERVICE_BASE64_HOPPSCOTCH : clé stable de 32 caractères pour DATA_ENCRYPTION_KEY

Coolify génère un domaine aléatoire au premier déploiement. Il est ensuite modifiable dans l'UI Coolify sur le service hoppscotch. Les URLs app/admin/backend sont dérivées par sous-chemins automatiquement.

Démarrer avec le tag latest :

make prod-up

Démarrer avec un autre tag :

make prod-up TAG=fork-v1.0.0

Voir les logs :

make prod-logs

Voir l'état des services :

make prod-ps

Arrêter :

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 :

make dev-up

Alias :

make up

Voir les logs :

make dev-logs

Voir l'état :

make dev-ps

Arrêter :

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 :
make docker-build-push-images TAG=latest
  1. Déployer :
make prod-up
  1. Contrôler :
make prod-ps
make prod-logs