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 générées/préremplies pour Coolify :

• COOLIFY_URL : URL publique du service, issue du domaine renseigné dans Coolify
• COOLIFY_FQDN : domaine public sans schéma, issu du domaine renseigné dans Coolify
• SERVICE_PASSWORD_POSTGRES : mot de passe PostgreSQL généré
• SERVICE_BASE64_HOPPSCOTCH : clé stable générée de 32 caractères pour DATA_ENCRYPTION_KEY

Ne pas modifier les variables SERVICE_FQDN_* / SERVICE_URL_* dans Coolify : elles sont générées et peuvent être écrasées. Renseigner uniquement le domaine du service hoppscotch dans Coolify. Les URLs app/admin/backend sont ensuite dérivées par sous-chemins via COOLIFY_URL et COOLIFY_FQDN.

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

4. Déployer :

make prod-up

5. Contrôler :

make prod-ps
make prod-logs