Deployment

How the static docs build, generated API contract, and Storybook output are assembled for publication.

Static Output

The docs site is an Astro app that builds to docs/dist. It owns the public homepage, documentation routes, generated OpenAPI explorer, and static Storybook output on the public host. Pages are still prerendered as static files, while Astro’s ClientRouter turns internal navigation into a SPA-style experience.

bash
pnpm build:docs

Build Steps

The docs build publishes the shared UI Storybook output into docs/public/storybook, then runs astro build. Astro copies that Storybook artifact into docs/dist/storybook with the rest of the static site.

This keeps API reference, documentation pages, and component examples in the same deployable artifact.

Regenerate the OpenAPI contract separately when backend routes change:

bash
pnpm generate:openapi

Route Ownership

The public host owns /, /docs/*, /openapi/, and /storybook/ through GitHub Pages. The app host owns product routes such as /login, /register, and authenticated dashboard paths, while /api/* on that host is proxied to the Go controller. Observability deployments can map Grafana directly to grafana.netstamp.dev.

Self-Host Runtime

The default self-host runtime is deployments/docker/compose.yaml. It pulls the yorukot/netstamp app image, runs PostgreSQL/TimescaleDB, applies migrations through a one-shot service, and serves the React app plus /api/v1/* from the Netstamp container.

bash
curl -O https://raw.githubusercontent.com/yorukot/netstamp/main/deployments/docker/compose.yaml
curl -O https://raw.githubusercontent.com/yorukot/netstamp/main/deployments/docker/example.env
cp example.env .env
docker compose up -d

Use an external reverse proxy for public HTTPS deployments.

Verification

Run a docs build before publishing changes that touch MDX, navigation, shared UI Storybook output, or Astro layout code. Run pnpm generate:openapi before that build when backend API routes or schemas change.