Skip to content

The Publish workspace

One fictional product — a multi-tenant publishing platform — told through five apps that share features and never call each other over RPC.

Publish is the story the NestRS monorepo tells. Not a crate name — a multi-tenant publishing platform: publications (orgs), authors (users), posts, live comments, background jobs, and an MCP assistant for drafting. Several binaries, one workspace, shared crates/features/, no chatty RPC between deployables — a modular monolith, deployed per workload, at full size.

Three names run through every page of these docs, and this is the whole map. hello is the one-route binary nestrs new writes, blog is what the tutorial builds on top of it, and Publish is the finished workspace every reference page draws its users, orgs, posts and audio snippets from. The first two you scaffold in your own workspace with nestrs new; only Publish is hosted in this repository. A snippet naming posts is Publish’s unless the page says otherwise.

AppPortRole in the storyTransports
auth3001Authors sign in (OAuth2, JWT issuance)HTTP
api3002Main API — users, orgs, posts, audio hooksHTTP, GraphQL, OpenAPI, Schedule
assistant3003AI tools over audio, users and posts (JWT-guarded)MCP
live3004Live comments and notificationsWebSockets
worker3005Async jobs — notifications, audio queueQueue, Schedule, HTTP (health only)
Terminal window
git clone https://github.com/YV17labs/NestRS && cd NestRS/demo
nestrs run db up # Postgres — api + auth
nestrs run dev auth # issuer on :3001
nestrs run dev api # resource server on :3002
nestrs run dev live # WebSockets on :3004
nestrs run dev assistant # MCP on :3003
nestrs run dev worker # jobs, health on :3005 — needs Redis

api and auth share the same database and the features crate; the worker shares Redis with the API’s queue producer. Tokens are self-contained JWTs — the API verifies with a public key, never calls the issuer over HTTP.

Every app reads the workspace’s .env files, and what is one app’s alone sits in its own apps/<app>/.env: its port, the audience it requires — its own origin, so a token minted for one app is refused by the others. auth’s .env.development and .env.test add the signing key, the registered clients and the resources a sign-in may name (an app’s own files).

The workspace ships a container and a Helm chart. One image holds every binary, so a Deployment’s command is the whole difference between the five apps — demo/Dockerfile builds it, and the chart under demo/charts/demo/ deploys it.

Terminal window
openssl genpkey -algorithm ed25519 -out signing.pem
openssl pkey -in signing.pem -pubout -out verifying.pem
helm install demo demo/charts/demo \
--set apps.auth.host=auth.example.com \
--set apps.api.host=api.example.com \
--set apps.assistant.host=assistant.example.com \
--set apps.live.host=live.example.com \
--set secrets.SEAORM__URL="postgres://user:pass@db:5432/nestrs" \
--set secrets.REDIS__URL="rediss://redis:6379" \
--set secrets.REDIS__TRANSCODES__URL="rediss://cache:6379" \
--set secrets.STORAGE__ACCESS_KEY="$STORAGE_ACCESS_KEY" \
--set secrets.STORAGE__SECRET_KEY="$STORAGE_SECRET_KEY" \
--set-file secrets.AUTHN__PRIVATE_KEY=signing.pem \
--set-file secrets.AUTHN__PUBLIC_KEY=verifying.pem \
--set-file secrets.OAUTH__SERVER__CLIENTS=clients.json

The secrets are the Required list in values.yaml: a cluster’s own services, the object store’s credentials, the signing keypair, and clients.json, the array of clients auth registers, each with its client_id, client_secret, payload, scopes and resources. The chart derives the cross-app URLs from the hostnames, and each app’s audience from its own. Leave out a secret, or the hostname of api, assistant, auth or live, and the install is refused, naming each setting and the apps that cannot run without it: an app reading one refuses its boot without it, but for the signing key, without which auth boots and its token endpoint answers 500. An app kept off the Ingress pins its AUTHN__AUDIENCE in its own config instead. Social sign-in stays optional: a provider is on once a deployment names its CLIENT_ID and CLIENT_SECRET, and one of the two alone is refused like a missing secret.

Each app has a Secret of its own, holding the keys of secrets it reads and no other: auth’s signing key and registered clients reach auth alone, and the migration job holds the database URL. What an app reads is its reads in values.yaml, read off its modules; a key no app reads refuses the install. A key changed rolls every app reading a Secret the chart writes, under one checksum of them all: a pod is read where a Secret is not, and a checksum of one app’s Secret alone would test a guess at the secret it holds. To bring your own, apps.<name>.existingSecret hands one app a Secret of yours in place of the chart’s, and defaults.existingSecret every app the same one.

Every app is declared in one map, and kind says what it becomes in the cluster. Migrations are an app like the others — the same image, another binary — rendered as a job that runs to completion before any deployment is updated.

charts/demo/values.yaml
apps:
migrate: { kind: job, bin: migrate, args: [up] }
api: { bin: api, port: 3002, host: api.example.com, ingress: true }
worker: { bin: worker, port: 3005 }

Set the hostnames rather than the URLs. The apps address each other by URL — the issuer a token is signed by, the audience each app requires, the resource identifier discovery serves, the resources a sign-in may be minted a token for — and each of those is some app’s public origin, so the chart derives them from apps.<name>.host. Each app requires its own origin as a token’s audience, so a token minted for one is refused by the others, and the signing key reaches auth alone.

Each app’s pod sleeps five seconds in a preStop hook before its SIGTERM, so it leaves its Service while it still listens, and the 35-second grace holds that sleep and the framework’s way down — see leaving the load balancer first.

Scaling the queue worker is the one decision the chart does not make for you. Each #[process] method runs at most its declared concurrency per pod — one unless it says otherwise — and Publish’s processors are I/O, an S3 round-trip or one INSERT, so a pod draining thousands of jobs sits near 0% CPU and a CPU-driven autoscaler never fires. Queue depth is the signal that moves with the work, and KEDA is what reads it: the chart ships a trigger on each queue’s nestrs:queue:{<queue>}:jobs stream, disabled until you turn it on. The chart’s README carries the trade-offs, including why replicas stop at one rather than zero.

Three entry points — two learning paths (CLI) and one hosted reference (this repo):

  • Getting started and the tutorial scaffold hello and blog with the CLI — reproducible in any workspace, not checked into this repo.
  • Fundamentals walks blog step ① — a feature adapter and the root importing it (vocabulary only). The tutorial builds the composed layout from page 1 onward.
  • Reference pages (HTTP, GraphQL, queue, MCP, …) point at the matching Publish app above — the complex example you clone and explore.
Feature (crates/features/)Publish role
postsBlog articles — api (HTTP, org + author scoped)
usersAuthors and editors — api
orgsPublications / tenants — api
sign_inPassword and social sign-in, token issuance — auth
chatLive comments — live
notificationsNotifications — api, live, worker
auditThe audit trail on writes — api
audioMedia attachments + queue/schedule hooks
authn / authzJWT verification and row-level policy — api, not the tutorial blog