# Coffee Break — local PostgreSQL order lab

This is the local, write-capable companion to the VKS articles. It models the reference app’s browser → HTTP API → shared PostgreSQL path. Bun 1.4.4 and Docker Compose are used. PostgreSQL is reachable only inside the Compose network; the app binds to `127.0.0.1:18081`.

Download or inspect the project files: [`server.ts`](./server.ts), [`index.htm`](./index.htm), [`app.js`](./app.js), [`style.css`](./style.css), [`Dockerfile`](./Dockerfile), [`compose.yaml`](./compose.yaml), and [`verify.mjs`](./verify.mjs). The browser page reads the menu and submits a replenishment request. `GET /menu` returns current stock and release. `POST /orders` accepts JSON with a SKU and quantity from 1 to 20 plus an `Idempotency-Key`; a new order returns `201 Created` and an identifier. `GET /orders/{id}` reads the durable order record. An accepted order does not increment stock or promise that coffee has been prepared or delivered.

## Run the browser demo

From this directory, create a random local database password in the shell environment without printing its value, then start the project:

```sh
export CAFE_DB_PASSWORD="$(openssl rand -hex 24)"
docker compose up --build --wait -d
```

Open <http://127.0.0.1:18081>. The database has no host-published port. To stop the demo and remove its disposable database volume:

```sh
docker compose down --volumes --remove-orphans
unset CAFE_DB_PASSWORD
```

## Run the disposable verification

With Docker Compose available and the local port free, run:

```sh
bun --version
bun verify.mjs
```

The verifier starts the app and PostgreSQL with a fresh random password, checks HTTP behavior and persistence, then removes its Compose project and database volume in `finally`. It also writes `verification.json` in this directory; set `CAFE_REPORT_FILE` to choose another existing output directory. Checks include same-key retry (`200`), changed-body key reuse (`409`), eight concurrent retries creating one order, reading the order after an app restart and v2 release, and unchanged stock. It also checks invalid quantity (`422`) and cross-origin rejection (`403`). Compose caps container resources, and the verifier checks that the shared Docker ceiling of eight containers has room before starting.

The recorded run passed on 27 October 2026 in isolated local Docker/PostgreSQL. It did not exercise VKS, ingress, TLS, SSO, high availability or GitOps. The local lab intentionally has no SSO; production requires platform-approved identity and authorization. The app uses Bun’s built-in SQL client for PostgreSQL: [Bun SQL documentation](https://bun.com/docs/runtime/sql).

---

# Pause Café — labo local avec commandes PostgreSQL

Ce labo local, avec écriture, complète les articles VKS. Il représente le parcours de l’application de référence : navigateur → API HTTP → PostgreSQL partagé. Il utilise Bun 1.4.4 et Docker Compose. PostgreSQL reste accessible uniquement dans le réseau Compose ; l’application écoute sur `127.0.0.1:18081`.

Télécharge ou consulte les fichiers du projet : [`server.ts`](./server.ts), [`index.htm`](./index.htm), [`app.js`](./app.js), [`style.css`](./style.css), [`Dockerfile`](./Dockerfile), [`compose.yaml`](./compose.yaml) et [`verify.mjs`](./verify.mjs). La page lit le menu et soumet une demande de réapprovisionnement. `GET /menu` renvoie le stock courant et la version. `POST /orders` accepte un JSON avec un SKU et une quantité de 1 à 20, ainsi qu’un `Idempotency-Key` ; une nouvelle commande renvoie `201 Created` et un identifiant. `GET /orders/{id}` relit l’enregistrement durable. Une demande acceptée n’augmente pas le stock et ne promet ni préparation ni livraison du café.

## Lancer la démo navigateur

Depuis ce dossier, crée un mot de passe aléatoire dans l’environnement local du shell sans afficher sa valeur, puis démarre le projet :

```sh
export CAFE_DB_PASSWORD="$(openssl rand -hex 24)"
docker compose up --build --wait -d
```

Ouvre <http://127.0.0.1:18081>. La base n’expose aucun port sur l’hôte. Pour arrêter la démo et supprimer son volume de base jetable :

```sh
docker compose down --volumes --remove-orphans
unset CAFE_DB_PASSWORD
```

## Exécuter la vérification jetable

Avec Docker Compose disponible et le port local libre, lance :

```sh
bun --version
bun verify.mjs
```

Le vérificateur démarre l’application et PostgreSQL avec un nouveau mot de passe aléatoire, vérifie le comportement HTTP et la persistance, puis supprime le projet Compose et son volume dans `finally`. Il écrit aussi `verification.json` dans ce dossier ; `CAFE_REPORT_FILE` permet de choisir un autre dossier de sortie existant. Il vérifie qu’une répétition avec la même clé renvoie `200`, qu’une réutilisation avec un corps différent renvoie `409`, que huit répétitions concurrentes ne créent qu’une commande, et que la commande reste lisible après redémarrage de l’application et passage à la version v2. Le stock reste inchangé. Le script vérifie aussi une quantité invalide (`422`) et un refus cross-origin (`403`). Compose limite les ressources des conteneurs, et le vérificateur s’assure que le plafond Docker partagé de huit conteneurs laisse de la place avant de démarrer.

La vérification enregistrée a réussi le 27 octobre 2026 dans un environnement Docker/PostgreSQL local isolé. Elle n’a pas testé VKS, ingress, TLS, SSO, haute disponibilité ou GitOps. Le labo local ne fournit volontairement pas de SSO ; la production doit appliquer l’identité et les autorisations approuvées par la plateforme. L’application utilise le client SQL intégré à Bun pour PostgreSQL : [documentation SQL de Bun](https://bun.com/docs/runtime/sql).
