Deployment topologies

The same image runs all of them. The container argument selects the mode: server (default), worker, or service <module>…​.

Three things default to a single-process adapter. All three have a replica-safe one; each is configuration rather than code, and none of them is on by default. Only the rate limiter below was exercised across running replicas; the realtime and event-bus claims are read from the adapters and their tests, not from a topology brought up here.

Rate limiting needs a shared cache. A limit counted in one JVM is not a limit when there are three. With Redis behind it the counter is shared — verified by setting the limit to 5 across two replicas and sending twelve requests through the load balancer:

The application refuses to start with rate limiting enabled and no reachable cache, which is the right failure — but :wagoe/cache ships under :inactive in resources/conf/prod/config.edn. Move it to :active and point it at Redis. That is an edit to your own config file; no environment variable does it, which is why the compose reference deploys Redis but leaves HTTP_RATE_LIMIT_ENABLED off.

Realtime pub/sub needs :provider :redis. Under the default :in-memory provider a WebSocket connected to replica A does not see an event published on replica B, and sticky sessions do not fix it — the publisher and the subscriber are different connections. The Redis provider (BOU-85, ADR-035) fans routing envelopes out over a pub/sub channel and keeps topic subscriptions in Redis sets, so a broadcast reaches clients on any replica. Sockets stay node-local under both providers; only the bus and the pub/sub manager differ.

Note what "configuration" means here: the monorepo’s wagoe.config/ig-config does not emit :wagoe/realtime at all, so an application that wants realtime wires the component itself against wagoe.realtime.shell.module-wiring. Getting this wrong is quiet — a config with no :provider gets :in-memory, and the single-node behaviour is a default rather than an error. Config shape is in that namespace’s docstring.

The event bus needs :provider :redis-streams (BOU-93, libs/events) — :redis-streams, not :redis, which is the cache’s and realtime’s spelling and not this one’s. Redis Streams with consumer groups delivers an event once per logical subscriber across replicas; the in-memory adapter delivers it only within the publishing process.

Two ways this differs from realtime above. :wagoe/events is wired from config — move it into :active and the component is emitted — though it is absent from the shipped prod profile, so it is off until you add it. And it has no default: any provider other than :redis-streams or :in-memory, including none at all, throws Unknown event bus provider at boot. Loud rather than quiet, which is the better of the two failures here.

Scheduled jobs are not on this list, contrary to the usual expectation. Promotion of a due job is an atomic claim — ZREM on the scheduled sorted set, and only the worker whose ZREM returns 1 owns it — so N workers polling concurrently promote each due job exactly once (BOU-88). There is no recurring or cron scheduler in the framework, so there is nothing that fires per process at start-up either. Running more than one worker is safe; job handlers must be idempotent for the ordinary at-least-once reason, not because of duplicate scheduling.

Point readiness probes at /health/ready and liveness at /health/live. Both are already served; the manifests wire them.

The prod profile reads these. Names matter: POSTGRES_*, not DB_* — the wrong name fails the boot at :wagoe/db-context with "Invalid database configuration", and until BOU-89 the shipped manifests had it wrong.

web publishes no host port. The load balancer is the only way in, which is what stops the replicas being decorative — with a published port, --scale collides and only one instance is ever reached.

To see the balancing, the load balancer logs which replica served each request:

The application’s own access logging skips the health endpoints, so without this there is nothing to look at.

Both are required — the compose file refuses to interpolate without them, which is deliberate: a secret with a default is a secret nobody sets.

service user boots the user module and the platform it needs — 20 of 29 components in the prod profile — and serves IUserService on port 3001 for the rest of the deployment. The composition is logged at start-up, including what was left out, so a service that quietly kept everything is visible rather than merely healthy.

The app container in that file is an ordinary server, and still runs its own copy of the user module. Pointing it at the remote one means building the adapter in place of the local component:

That is a wiring decision in an application’s own config — which component a key resolves to — not something a framework reference can make for it. The compose file says so rather than setting a URL that nothing reads.

One process serves one protocol. The catalogue already declares an RPC protocol for both user and payments, so service user payments is refused at start-up with both named, in any profile where both modules are active. Serving the first and carrying on would leave the other reachable by nobody, with a healthy process and nothing in the log. Run them as separate services, or drop :wagoe/rpc to run them together with neither reachable.

The RPC port is published to nothing. It invokes port methods directly, so it belongs on the internal network:

Which modules can run this way is declared in the service catalogue — see Running a module as a service. A module that is :inactive in your config cannot: service payments against the stock prod profile is refused with "This configuration builds nothing for: payments. The module is probably disabled in config." Enable the module first.

deploy/k8s/wagoe.yaml is one file with the whole set: Secret, ConfigMap, the server Deployment and its Service, the worker Deployment, Redis, an Ingress, and a module-as-a-service Deployment with a ClusterIP Service on the RPC port only.

Replace REGISTRY/wagoe:TAG and the Secret values. The manifests validate against upstream schemas (kubeconform -strict); they have not been applied to a running cluster as part of this work, so treat resource requests, the Ingress class and storage as starting points for your environment rather than as tested values.

Two details worth keeping when you adapt them: