Skip to main content

​
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:
licence.key and licence.existingSecretRef.name are mutually exclusive. Setting both fails the install with a named error rather than silently preferring one.

​
Step 2: Install the chart

We send you the chart as a file — swarmd-<version>.tgz — over whatever channel we agreed, with your licence key delivered separately. Point Helm straight at it:
That’s the whole command. Everything else has a working default.
Nothing to log in to. The chart is a self-contained file, so Helm needs no registry access and you need no credentials on your workstation. Your cluster still pulls Swarmd’s private images, but it sorts that out on its own: a pre-install Job exchanges the licence key in your Secret for image-pull credentials and a CronJob refreshes them every 8 hours. You never wire that up by hand. See Licence and images.
The version is the filename. There is no --version flag to get wrong and no “latest” to resolve — the file you were sent is the release, which is also what makes it easy to say exactly what a cluster is running.Keep the file. It is what helm rollback cannot give you back if you need to reinstall an older release from scratch.
The chart carries its own values.yaml and a set of tested presets. Unpack it alongside the tarball to read or copy them — you still install from the file itself:
Then install with a preset:
helm show values $SWARMD_CHART prints the defaults without unpacking anything.
  1. 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.
  2. A pre-install Job fetches image-pull credentials. It calls the licence server with your key and writes the result as a dockerconfigjson Secret. This has to succeed before anything else — without it the cluster cannot pull Swarmd’s images. See Licence and images.
  3. A credentials Secret is generated. Postgres, Keycloak admin and ClickHouse passwords, plus an encryption key — 24 random alphanumeric characters each.
  4. Postgres and Keycloak start, and a bootstrap Job loads the Swarmd realm.
  5. Migration Jobs run Flyway, then the services and UI roll out.

​
Step 3: Watch it come up

Expect every pod 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 and wants roughly 12 GiB. See Scaling: core and worker for why, and how to collapse it on a laptop.
Init:0/1 for the first minute is the gate, not a hang. Each service waits on a wait-for-keycloak init container until Keycloak’s realm answers, so nothing races it during startup. Once past that, expect zero restarts — a service restarting is worth investigating rather than waiting out. See Startup ordering.
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.
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:
Repeat every --set from the install — Helm does not carry values forward between releases. Once you have more than a couple, move them into a values file and pass -f; see Your own values file.
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:
Open http://localhost:3000 and create your tenant and first admin user through the sign-up flow.
Email is off by default, which makes this a one-account deployment. The admin you just created can sign in normally — but invite and password-reset emails are logged and dropped, so you cannot add a second user, and a forgotten password can only be fixed by a Keycloak admin.Fine for a first look. Wire up SMTP before anyone else needs access.
You’ll also want the API gateway reachable — it’s what agents and SDKs talk to:
Ready for real hostnames instead? → Ingress.
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.
From there the Python SDK and the TypeScript channel client apply exactly as written.

​
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.

Plan your first upgrade

What survives a version bump, how to preview one, and the credential rotation to avoid.

Start from a preset

Eight tested shapes, laptop through hardened production.

​
Uninstalling

PVCs and the generated credentials Secret survive on purpose — the Secret carries helm.sh/resource-policy: keep, so a reinstall reuses the same passwords and your data is still there. To destroy the data too:
That is irreversible.