api-client/README.md

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

- `SERVICE_FQDN_HOPPSCOTCH_80` : domaine public unique du service
- `SERVICE_FQDN_HOPPSCOTCH` : URL publique générée depuis le domaine
- `SERVICE_URL_HOPPSCOTCH` : domaine sans schéma, utilisé pour le WebSocket
- `SERVICE_PASSWORD_POSTGRES` : mot de passe PostgreSQL généré
- `SERVICE_BASE64_DATA_ENCRYPTION_KEY` : clé stable générée de 32 caractères pour `DATA_ENCRYPTION_KEY`

Après l'import du compose dans Coolify, renseigner uniquement le domaine du
service `hoppscotch`. Les URLs app/admin/backend sont ensuite dérivées 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
```