Self-Hosting
The Quickstart gets a single instance running in one command. This page is the production view: the three ways to run Truss — Docker Compose for a single box, the Helm chart for Kubernetes, and the operator for declarative / fleet management — plus the first-login flow and the hardening you should do before exposing it to the internet.
None of these paths needs a repo clone. All pull the published (cosign-signed)
ghcr.io/binarysquadd/truss-* images and bring up the full stack: the API, the dashboard,
Postgres, the Ory services (Kratos, Keto, Hydra, Oathkeeper), RustFS, flagd, and Valkey. The
current release is v0.4.0.
Docker Compose
Section titled “Docker Compose”For a single host. Download the Compose file and an env template, fill in secrets, and start:
curl -fsSLO https://raw.githubusercontent.com/binarysquadd/truss/main/docker-compose.selfhosted.ymlcurl -fsSL https://raw.githubusercontent.com/binarysquadd/truss/main/.env.selfhosted.example -o .env.selfhosted
# fill in every GENERATE_* value, e.g. with: openssl rand -hex 32
docker compose -f docker-compose.selfhosted.yml --env-file .env.selfhosted up -dThe dashboard is served at http://localhost:3000. (Prefer one command? The
Quickstart installer does the download + secret generation for you.)
The MCP server is an optional add-on, off by default. Turn it on with
docker compose -f docker-compose.selfhosted.yml --profile mcp up -d; it listens at
http://localhost:8765/mcp.
By default the Compose file uses the published ghcr.io/binarysquadd/truss-* images. To build
from source instead, clone the repo and uncomment the build: blocks in the file.
Kubernetes (Helm)
Section titled “Kubernetes (Helm)”The chart is published (and cosign-signed) as an OCI artifact, so one helm install pulls it
directly. No operator, no clone. Secrets you leave unset are auto-generated on first install
and reused across upgrades, so a bare install just works:
helm install truss oci://ghcr.io/binarysquadd/charts/truss --version 0.4.0 \ -n truss --create-namespace
kubectl -n truss port-forward svc/truss-dashboard 3000:8080 # → http://localhost:3000Bring your own secrets with --set secrets.encryptionKey=… (or from an external secret manager);
any left blank are generated. Images are pinned in the chart and overridable via images.*. For
production set publicUrl + corsAllowedOrigins and front it with TLS. Toggle optional components
with their flags (e.g. --set mcp.enabled=false), and turn on the bundled 4-signal observability
stack (Grafana / Prometheus / Loki / Tempo) with --set observability.backends.enabled=true.
Kubernetes (Operator)
Section titled “Kubernetes (Operator)”The operator is the declarative, fleet-friendly path: you apply a TrussInstance custom resource
and a controller reconciles the whole stack to match — healing drift, reporting status conditions,
and (optionally) emitting a ServiceMonitor + multi-window burn-rate SLO PrometheusRule for your
Prometheus stack.
It manages the app tier (API + dashboard) and, when you ask for it, the full dependency
stack: managed Postgres with HA via CloudNativePG (the medium /
large profiles run 3 instances), plus managed RustFS, Valkey, and flagd, a pre-roll migration
Job, and scheduled backups + PITR. Each dependency defaults to managed (the operator
provisions it); set mode: byo + an existingSecret to point at your own instead. The operator
also runs itself HA (2 replicas + leader election) and serves a v1beta1 API alongside v1alpha1
through a conversion webhook.
Install the controller + CRDs from the release bundle, then apply an instance:
kubectl apply -f https://github.com/binarysquadd/truss/releases/download/v0.4.0/install.yamlkubectl create namespace truss
kubectl apply -f - <<'EOF'apiVersion: apps.truss.binarysquad.org/v1beta1 # v1alpha1 is still served via the conversion webhookkind: TrussInstancemetadata: { name: truss, namespace: truss }spec: version: "0.4.0" host: truss.example.com # required when ingress.enabled (v1alpha1 calls this publicURL) scaling: { profile: small } # small | medium | large dependencies: postgres: { mode: managed } # operator provisions a CloudNativePG cluster storage: { mode: managed } # RustFS cache: { mode: managed } # Valkey flags: { mode: managed } # flagd observability: serviceMonitor: true # created only if the Prometheus-operator CRDs exist prometheusRule: true otlpEndpoint: http://otel-collector.monitoring:4318 # optional: push traces/metrics/logsEOF
kubectl -n truss get trussinstance truss -o jsonpath='{.status.phase}' # → ReadyTo bring your own Postgres instead, create a Secret with a database-url key and set
postgres: { mode: byo, existingSecret: <name> }.
First login
Section titled “First login”On first boot, with no account yet, Truss seeds a default admin so you can sign in immediately, the same way Grafana and Argo CD do. It only ever runs when the identity store is empty, so it never overwrites real users.
-
Email:
admin@truss.local(override withTRUSS_BOOTSTRAP_ADMIN_EMAIL). -
Password: set
TRUSS_BOOTSTRAP_ADMIN_PASSWORDfor a known value, or leave it blank and a random one is printed once to the API logs:Terminal window docker compose -f docker-compose.selfhosted.yml logs truss-api | grep "Default admin" # Composekubectl -n truss logs deploy/truss-api | grep "Default admin" # Kubernetes
Change it right after logging in under Settings → Account → Change Password. To opt out
entirely, set TRUSS_BOOTSTRAP_ADMIN=false and register the first user yourself.
See Configuration for the full list of environment variables.
Hardening (read before exposing to the internet)
Section titled “Hardening (read before exposing to the internet)”CORS_ALLOWED_ORIGINS— set to your dashboard origin(s). CORS fails closed; if unset, the browser app cannot reach the API (intentional).ENCRYPTION_KEY— a random 32+ char string used to encrypt saved connection passwords. If you lose it, those are unrecoverable. The Helm chart and operator auto-generate and persist it (in thetruss-secretsSecret); on Compose you set it yourself. Either way, back it up — and note the app refuses to start in production with a placeholder (change-me…) value.COOKIE_SECURE— the session cookie is markedSecureonly when you serve over HTTPS. Serving over plain HTTP keeps it off so the cookie is not dropped; setCOOKIE_SECURE=truebehind an HTTPS-terminating proxy the API cannot detect.TRUSS_ADMIN_IDENTITY_IDS— admin-only features (DB roles, migrations, backups, authz rules) are gated. Grant admin by setting this to your Kratos identity ID(s), comma-separated.- Put the API behind TLS, run Postgres with backups (PITR), and never run with dev defaults.
Ready to stop running it yourself?
Section titled “Ready to stop running it yourself?”If self-hosting has done its job and you would rather hand off the ops, Truss Cloud is the same platform, hosted and managed, with multi-org, metering, and managed backups. Your client code and API surface stay the same.