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.
The apps
Section titled “The apps”| App | Port | Role in the story | Transports |
|---|---|---|---|
auth | 3001 | Authors sign in (OAuth2, JWT issuance) | HTTP |
api | 3002 | Main API — users, orgs, posts, audio hooks | HTTP, GraphQL, OpenAPI, Schedule |
assistant | 3003 | AI tools over audio, users and posts (JWT-guarded) | MCP |
live | 3004 | Live comments and notifications | WebSockets |
worker | 3005 | Async jobs — notifications, audio queue | Queue, Schedule, HTTP (health only) |
git clone https://github.com/YV17labs/NestRS && cd NestRS/demonestrs run db up # Postgres — api + authnestrs run dev auth # issuer on :3001nestrs run dev api # resource server on :3002nestrs run dev live # WebSockets on :3004nestrs run dev assistant # MCP on :3003nestrs run dev worker # jobs, health on :3005 — needs Redisapi 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).
Deploy it
Section titled “Deploy it”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.
openssl genpkey -algorithm ed25519 -out signing.pemopenssl 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.jsonThe 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.
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.
How the docs use Publish
Section titled “How the docs use Publish”Three entry points — two learning paths (CLI) and one hosted reference (this repo):
- Getting started and the tutorial scaffold
helloandblogwith the CLI — reproducible in any workspace, not checked into this repo. - Fundamentals walks
blogstep ① — 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 map
Section titled “Feature map”Feature (crates/features/) | Publish role |
|---|---|
posts | Blog articles — api (HTTP, org + author scoped) |
users | Authors and editors — api |
orgs | Publications / tenants — api |
sign_in | Password and social sign-in, token issuance — auth |
chat | Live comments — live |
notifications | Notifications — api, live, worker |
audit | The audit trail on writes — api |
audio | Media attachments + queue/schedule hooks |
authn / authz | JWT verification and row-level policy — api, not the tutorial blog |
Going further
Section titled “Going further”- Split deployment — why auth is a separate binary.
- Build a feature end to end — scaffold your own
apps/blog/. - E2E testing — every Publish app ships
tests/e2e/main.rs.