# Miabi Guestbook — example app A tiny, self-contained web app used as a **reference for deploying to [Miabi](https://github.com/miabi-io/miabi)**. It is a classic guestbook: visitors leave a name and a message, and the wall shows every signature. It deliberately exercises everything a real Miabi deployment touches, in miniature: - **[Okapi](https://github.com/jkaninda/okapi) (Go)** REST API, driven by **`okapicli`** — a `server` subcommand with graceful-shutdown lifecycle hooks (the same CLI layout Miabi uses) - **SPA served by `app.WebFS`** — the embedded UI is mounted straight from an `embed.FS`; Okapi serves real assets and falls back to `index.html` for client-side routes (home + an **All signatures** page), while registered API routes keep precedence - **Live updates over SSE** — new/removed signatures stream to every open tab, with a real-time **connected-clients** ("N online") indicator - **Version badge + live server-time card** — the serving build's version is shown in the UI and `/api/info`, and a **live clock** (streamed over SSE with the server's `version` + `host`) makes a **canary rollout** obvious: the card is new in v2, and its time/host reveal exactly which build/replica served you - **[GORM](https://gorm.io) with PostgreSQL _or_ SQLite** — `uint` PKs and soft deletes, the same conventions Miabi uses. Attach a Miabi managed Postgres, or fall back to a zero-config SQLite file (pure-Go driver, no CGO). - **Structured logging** via [`jkaninda/logger`](https://github.com/jkaninda/logger) - **Env-based config** — auto-detects the driver; reads `DATABASE_URL` / `DB_*` - **`AutoMigrate` on startup** with retry (tolerates the DB coming up a beat later) - **First-run seeder** — populates the wall when the table is empty (`SEED=false` to skip) - **`/healthz` readiness probe** that returns `503` until the database is reachable - **Single static binary** — the whole UI is embedded with `go:embed`, so the image is one distroless layer with **no Node build step** ## Why this UI approach For an example that should deploy in seconds, the frontend is a **single embedded `index.html`** — modern CSS (glassmorphism cards, gradient mesh, dark theme) plus a little vanilla JS calling the JSON API. No CDN, no bundler, no `node_modules`. It looks polished, loads instantly, works offline/air-gapped, and keeps the container tiny. ## API | Method | Path | Description | |----------|----------------------|------------------------------------| | `GET` | `/healthz` | Liveness/readiness (checks the DB), reports `version` | | `GET` | `/api/info` | App name, serving `version`, `host`, connected-client count | | `GET` | `/api/time` | Current server time + `version` + `host` (v2 — canary probe) | | `GET` | `/api/entries` | List entries + total; paginated via `?limit=&offset=` | | `POST` | `/api/entries` | Create `{ "name", "message" }` (broadcast live) | | `DELETE` | `/api/entries/{id}` | Delete an entry (broadcast live) | | `GET` | `/api/stream` | **SSE** stream: `welcome`, `created`, `deleted`, `presence`, `tick` events | | `GET` | `/` · `/all` | The web UI (home · all-signatures page) | ### Live updates (SSE) `/api/stream` is a Server-Sent Events endpoint. On connect the client gets a `welcome` event (serving version + host + online count); thereafter the server pushes `created` / `deleted` events as the wall changes, `presence` events when the connected-client count changes, and a `tick` event once a second carrying the live server time (with `version` + `host`). The UI uses these to update the wall in real time, show a live **“N online”** indicator, and drive the **server-time card** — all without polling. ## Configuration | Variable | Default | Purpose | |----------------|------------------|-------------------------------------------| | `PORT` | `8080` | HTTP listen port | | `APP_NAME` | `Miabi Guestbook`| Display name in the UI / health payload | | `APP_VERSION` | build version | Overrides the version shown in the UI / `/api/info`. Defaults to the value baked at build time (`-ldflags "-X main.version=…"`, or the `VERSION` build-arg). | | `SEED` | `true` | Seed sample entries on first run (empty table only) | | `DB_DRIVER` | _(auto)_ | `postgres` or `sqlite`. Unset → auto: Postgres when configured, else SQLite. | | `DB_PATH` | `data/guestbook.db` (`/data/guestbook.db` in the image) | SQLite file path (or `:memory:`). Its parent dir is created on startup. The container stores it on the `/data` volume. | | `DATABASE_URL` | — | Full Postgres DSN (URL or key=value). Preferred — set for you when you attach a Miabi **managed database**. Takes precedence over `DB_*`. | | `DB_HOST` | `localhost` | Database host (used when `DATABASE_URL` is empty) | | `DB_PORT` | `5432` | Database port | | `DB_USER` | `postgres` | Database user | | `DB_PASSWORD` | `postgres` | Database password | | `DB_NAME` | `guestbook` | Database name | | `DB_SSL_MODE` | `disable` | Postgres `sslmode` | > **On Miabi:** attach a managed database to the app and Miabi injects these > variables automatically — `DATABASE_URL` for the full DSN, plus the discrete > `DB_*` parts. You don't set them by hand. ## Run locally With Docker Compose (Postgres + app): ```bash docker compose up --build # open http://localhost:8080 ``` Or run the binary directly. With nothing configured it uses a zero-config SQLite file, so this just works: ```bash go run . # runs the default "server" command go run . server -p 9000 # okapicli flags: choose the port go run . --help # list commands and flags ``` To point it at your own Postgres, set `DATABASE_URL` (or the `DB_*` vars) first: ```bash cp .env.example .env # edit DATABASE_URL export $(grep -v '^#' .env | xargs) go run . ``` ## Build the image ```bash docker build --build-arg VERSION=1.0.0 -t miabi-guestbook:1.0.0 . docker run -p 8080:8080 -e DATABASE_URL=postgres://... miabi/guestbook:1.0.0 ``` The version can also be overridden at runtime with `-e APP_VERSION=…`. ## Canary deployment demo The version badge makes this app a ready-made **canary** example. Build two otherwise-identical images and let Miabi split traffic between them — the badge (and `/api/info`) tells you which build served each request: ```bash docker build --build-arg VERSION=1.0.0 -t miabi-guestbook:1.0.0 . docker build --build-arg VERSION=2.0.0 -t miabi/guestbook:2.0.0 . ``` 1. Deploy `1.0.0` as the app; attach a **shared** managed Postgres. 2. Roll out `2.0.0` as a **canary** with a small weight (e.g. 10%). 3. Refresh the page a few times: ~1 in 10 loads shows the `v2.0.0` badge (a different colour) **and the new live server-time card**, the rest `v1.0.0` without it. Because both versions share the same database, signatures created on either build appear on both — and stream live to every open tab via SSE. 4. Watch routing from the shell — each request may hit a different build/replica: ```bash watch -n1 'curl -s https://your-domain/api/time' # {"time":"…","version":"2.0.0","host":"…"} ← version/host flips under canary ``` 5. Shift the weight up and promote `2.0.0` when you're happy. > The server-time card is the **v2 change**: v1 (built before this feature) has > no clock, so its presence — and the version/host it shows — is an at-a-glance > signal of which build a viewer landed on. > No build args? Set `APP_VERSION=1.0.0` / `APP_VERSION=2.0.0` in each app's > environment instead — same effect. ## Deploy on Miabi 1. **Create a database** — provision a PostgreSQL database in your workspace. 2. **Create an application** — deploy this repo (Git build) or the image above. 3. **Attach the database** — Miabi injects the connection as `DATABASE_URL`. 4. **Set the health check** to `GET /healthz` and the port to `8080`. 5. **Connect a domain** — Miabi issues automatic SSL and routes traffic. The app migrates its schema on first boot, so there is no separate release step.