174 lines
3.3 KiB
Markdown
174 lines
3.3 KiB
Markdown
# Live Inventory CDC Demo
|
|
|
|
Small POC website showing browser CRUD actions flowing through Postgres, Debezium Server, NATS JetStream, a Go SSE backend, and back into the browser.
|
|
|
|
The important demo behavior is that mutation endpoints only return `command accepted`. The visible inventory cards are refreshed when the matching CDC event arrives over `/events`.
|
|
|
|
## Development Run
|
|
|
|
Development uses `compose.yml` for Postgres, NATS JetStream, Debezium, and helper containers. The Go web app runs as a native host process.
|
|
|
|
Install the host tools:
|
|
|
|
```bash
|
|
sudo dnf install golang podman
|
|
```
|
|
|
|
Use Taskfile as the main interface:
|
|
|
|
```bash
|
|
task --list
|
|
```
|
|
|
|
Terminal 1, start containerized Postgres, NATS, and Debezium:
|
|
|
|
```bash
|
|
task infra
|
|
```
|
|
|
|
Terminal 2, run the Go backend/frontend:
|
|
|
|
```bash
|
|
task backend
|
|
```
|
|
|
|
Then open:
|
|
|
|
```text
|
|
http://localhost:8080
|
|
```
|
|
|
|
Postgres is published to the host on:
|
|
|
|
```text
|
|
localhost:5453
|
|
```
|
|
|
|
NATS is published to the host on:
|
|
|
|
```text
|
|
localhost:4222
|
|
```
|
|
|
|
Development Debezium uses the internal compose addresses `postgres:5432` and `nats:4222`.
|
|
|
|
The Go backend defaults to:
|
|
|
|
```text
|
|
DATABASE_URL=postgres://postgres:postgres@localhost:5453/postgres?sslmode=disable
|
|
NATS_URL=nats://localhost:4222
|
|
```
|
|
|
|
## Production Run
|
|
|
|
Production uses user-level Podman quadlets for containers and a user systemd service for the Go backend.
|
|
|
|
Install the production units:
|
|
|
|
```bash
|
|
task prod:install
|
|
```
|
|
|
|
Start everything:
|
|
|
|
```bash
|
|
task prod:start
|
|
```
|
|
|
|
Stop everything:
|
|
|
|
```bash
|
|
task prod:down
|
|
```
|
|
|
|
Follow production logs:
|
|
|
|
```bash
|
|
task prod:logs
|
|
```
|
|
|
|
Production Debezium uses the internal quadlet network addresses `cdc-postgres:5432` and `cdc-nats:4222`.
|
|
|
|
## Production User Units
|
|
|
|
Quadlet files are installed to:
|
|
|
|
```text
|
|
~/.config/containers/systemd/
|
|
```
|
|
|
|
The Go backend service is installed to:
|
|
|
|
```text
|
|
~/.config/systemd/user/cdc-inventory.service
|
|
```
|
|
|
|
The service files are:
|
|
|
|
| Unit | Purpose |
|
|
|---|---|
|
|
| `cdc-postgres.service` | Postgres with logical replication enabled |
|
|
| `cdc-nats.service` | NATS JetStream |
|
|
| `cdc-debezium.service` | Debezium Server |
|
|
| `cdc-inventory.service` | Native Go backend/frontend |
|
|
| `cdc-seed.service` | One-shot seed helper |
|
|
| `cdc-inspect.service` | One-shot NATS inspect helper |
|
|
|
|
## Useful Checks
|
|
|
|
Inspect stream subjects and recent events:
|
|
|
|
```bash
|
|
task inspect
|
|
```
|
|
|
|
For production:
|
|
|
|
```bash
|
|
task prod:inspect
|
|
```
|
|
|
|
Generate a fresh burst of create/update/delete events:
|
|
|
|
```bash
|
|
task seed
|
|
```
|
|
|
|
For production:
|
|
|
|
```bash
|
|
task prod:seed
|
|
```
|
|
|
|
Stop development infrastructure:
|
|
|
|
```bash
|
|
task down
|
|
```
|
|
|
|
## Endpoints
|
|
|
|
| Method | Path | Purpose |
|
|
|---|---|---|
|
|
| `GET` | `/` | Demo page |
|
|
| `GET` | `/health` | Health check |
|
|
| `GET` | `/api/inventory` | Current database snapshot |
|
|
| `POST` | `/api/inventory` | Create inventory item |
|
|
| `PATCH` | `/api/inventory/{id}/sell` | Decrement quantity by 1 |
|
|
| `PATCH` | `/api/inventory/{id}/restock` | Increment quantity |
|
|
| `PATCH` | `/api/inventory/{id}` | Rename, move, or set quantity |
|
|
| `DELETE` | `/api/inventory/{id}` | Delete item |
|
|
| `GET` | `/events` | Server-Sent Events from CDC stream |
|
|
|
|
## Pipeline
|
|
|
|
```text
|
|
Browser action
|
|
-> Go backend writes to Postgres
|
|
-> Debezium captures the DB change
|
|
-> Debezium publishes to NATS JetStream
|
|
-> Go backend consumes the event
|
|
-> Go backend streams it to browser with SSE
|
|
-> Browser updates inventory and audit trail
|
|
```
|