Quickstart
By the end you’ll have the full platform running in your cluster and be signed in to the UI as your first admin user.Need the prerequisites? Overview → What you need.
The short version: a cluster with a default StorageClass, Helm 3, and a
licence key.Don’t have a key yet? Licences are issued per deployment —
talk to us and we’ll size the tier and get you
one. There is no self-serve path, and the cluster cannot pull Swarmd’s images
without it.
Step 1: Store your licence key
You can pass the key with--set licence.key=..., and for a throwaway test
that’s fine. Don’t do it for anything else: --set values are recorded in
Helm’s release history and visible to anyone who can run helm get values.
Put it in a Secret instead:
Step 2: Install the chart
What just happened, in order
What just happened, in order
- Validation runs first. The chart checks every combination it knows to
be broken — a missing external URL, an unknown
postgres.mode, SMTP enabled without credentials — and refuses to render with a specific message. Nothing reaches your cluster until it passes. - A pre-install Job fetches ECR credentials. It calls the licence server
with your key and writes the result as a
dockerconfigjsonSecret. This has to succeed before anything else — without it the cluster cannot pull Swarmd’s images. See Licence and images. - A credentials Secret is generated. Postgres, Keycloak admin and ClickHouse passwords, plus an encryption key — 24 random alphanumeric characters each.
- Postgres and Keycloak start, and a bootstrap Job loads the Swarmd realm.
- Migration Jobs run Flyway, then the services and UI roll out.
Step 3: Watch it come up
Ready in about three minutes on a fresh cluster —
longer on first pull, since the images come from ECR.
Three workloads per DB-backed service is expected, not a mistake: a
-migrate Job that runs Flyway once and exits, the API pod, and a -worker
pod running schedulers and outbox drainers. A default install is 18
Deployments. See
Scaling: core and worker
for why, and how to collapse it on a laptop.Pods stuck in ImagePullBackOff
Pods stuck in ImagePullBackOff
The licence loop failed. Check the bootstrap Job first — it’s the only thing
that can create the pull secret:The usual causes are a mistyped key, a licence that has expired or been
revoked, and no cluster egress to the licence server. Full breakdown in
Licence and images.
Postgres pod Pending
Postgres pod Pending
Almost always storage.
kubectl -n swarmd describe pvc will say so —
typically no default StorageClass, or a storageClass name that doesn’t
exist on this cluster:The install failed before creating anything
The install failed before creating anything
That’s the validation gate, and the message names the exact value to fix.
It runs before any resource is created, so there’s nothing to clean up —
correct the value and re-run.
Step 4: Get in
Ingress is off by default, so port-forward:Getting the Keycloak admin password
Getting the Keycloak admin password
The chart generates it. To reach the Keycloak admin console directly:The username is in the same Secret under
keycloak-admin-username. You
rarely need this — Swarmd manages realm objects for you — but it’s there for
debugging identity-provider setup.Step 5: Point an SDK at it
Your install is a complete Swarmd platform, so the SDKs work against it unchanged — you just override the two URLs:.env
Both URLs must point at the same install. A base URL from one environment
with a token URL from another mints tokens the gateway rejects on audience —
a
401 that looks like a bad secret but isn’t.Step 6: Make it real
The default install is deliberately minimal — it boots anywhere, needs no external accounts, and stores everything in one in-cluster Postgres. Before production:Pick a database layout
One Postgres, one per service, or your own managed instance.
Set up ingress and TLS
Traefik or AWS Load Balancer Controller.
Turn on SMTP
Without it, no user can verify an address or accept an invite.
Start from a preset
Eight tested shapes, laptop through hardened production.