Skip to content
excalibase
configuration
Self-hostingbeta

Configuration

Each setting is shown for both install modes: a chart value on Kubernetes (values.yaml, then helm upgrade) and a line in .env on a single host (then docker compose up -d). Every other chart value, with its comment, is in the chart itself:

helm show values excalibase/platform-aio --version 1.5.1

Email

Studio sends sign-up verification, invitations and password resets. Without a provider only the first admin can sign in; every other sign-up answers 503.

ProviderKubernetesSingle host .env
Your SMTP relayemail.provider: smtp, email.smtp.host, email.smtp.port, email.smtp.tls, email.smtp.credentialsSecret (keys username, password), email.smtp.caSecret (key ca.crt)EMAIL_PROVIDER=smtp, SMTP_HOST, SMTP_PORT, SMTP_TLS, SMTP_USERNAME, SMTP_PASSWORD
Amazon SESemail.provider: ses and a ses-creds SecretEMAIL_PROVIDER=ses, SES_ACCESS_KEY_ID, SES_SECRET_ACCESS_KEY, SES_REGION
Resendemail.provider: resend and a resend-creds Secret (key api-key)EMAIL_PROVIDER=resend, RESEND_API_KEY
Noneemail.provider: noopleave it unset

Sender: email.fromAddress / email.fromName (EMAIL_FROM_ADDRESS, EMAIL_FROM_NAME): an address your relay may send as.

SMTP TLS is starttls by default (port 587); tls is implicit TLS (465); none is plain text for a relay on your private network and refuses a password. Certificates are always verified: trust a private CA with caSecret rather than turning checks off. A malformed setting (no host, an unknown TLS mode, a password with none, an unreadable CA) stops the control plane at start, with the reason in its log. The relay itself is first contacted on the first email: a relay without STARTTLS, a certificate that does not verify or a wrong password shows up then, as a failed sign-up and in the log.

Object storage

Project backups (base backups and WAL), customer files (Storage) and the platform database's backups go to an S3-compatible store.

Bundled (default on a single host). A RustFS store inside the platform, one bucket and one key per use. Projects never get its key: each gets short-lived credentials for its own prefix. It is one copy on the same disk as your databases, so a lost disk loses the backups too: copy its volume off the machine, or use an outside bucket.

KubernetesSingle host
Turn onobjectStore.bundled.enabled: true with provisioning.backupCredentials.provider: stson by default
Where browsers open filesobjectStore.bundled.publicUrl (served by the edge)FILES_PUBLIC_URL (https://files.<domain>)
SizeobjectStore.bundled.storage (default 50Gi)the host's disk
Platform database backupsplatformDb.backup.enabled: true (+ schedule, retention)n/a (back up the volumes)

Your own bucket. Cloudflare R2, or any S3-compatible store that can issue scoped temporary credentials through STS (MinIO, RustFS elsewhere):

KubernetesSingle host .env
Project backupsSecret with access_key_id, secret_access_key, endpoint, bucket, region, named by provisioning.backupStore.secretName; provisioning.backupCredentials.provider: r2 for Cloudflare R2, sts for MinIO-style STSBACKUP_DEFAULT_ACCESS_KEY_ID, BACKUP_DEFAULT_SECRET_ACCESS_KEY, BACKUP_DEFAULT_ENDPOINT, BACKUP_DEFAULT_BUCKET, BACKUP_DEFAULT_REGION
Customer filesSecret storage-creds (same keys), its own bucket and key, with a CORS rule allowing GET, PUT, HEADSTORAGE_ACCESS_KEY_ID, STORAGE_SECRET_ACCESS_KEY, STORAGE_ENDPOINT, STORAGE_BUCKET, STORAGE_REGION
Platform databaseplatformDb.backup.s3.endpointURL, bucket, path, credentialsSecret (keys ACCESS_KEY_ID, ACCESS_SECRET_KEY)n/a

Project backups need temporary credentials scoped to one project, which AWS S3 issues only through an IAM role: use R2, MinIO or the bundled store for them. Customer files and the platform database work with any S3 store, AWS included. Keep backups and files in separate buckets with separate keys.

Vault unseal

The vault holds every project's database credentials and the token signing key. It is encrypted and must be unsealed with its key:

ModeKey keptAfter a restartKubernetesSingle host
Manualnowhere on the server: you keep itsealed until an admin unseals itvault.unseal.provider: manual./init.sh ... --manual-unseal
AWS KMSonly a ciphertext under your KMS keyunseals itselfvault.unseal.provider: awskms, vault.unseal.awskms.keyArn, region, credentialsSecretn/a
On the serverin a Secret / the control plane's volumeunseals itselfplaintext + devPlaintext: true (development only)the default

With manual unseal, Studio asks a platform admin to initialize the vault once and shows the key once: store it in a password manager or split it between people (Shamir shares). After every restart of the control plane (upgrade, reboot, eviction) projects stay unservable until someone unseals it, in Studio or from a shell:

kubectl -n excalibase-platform exec -it deploy/provisioning -- excalibase-provisioning vault unseal
docker exec -it excalibase-provisioning excalibase-provisioning vault unseal      # single host

Lose every copy of the key and the vault, with every project's credentials, cannot be recovered.

Sign-up and Studio access

KubernetesSingle host .env
Who may sign upprovisioning.registrationMode: open (default) or inviteREGISTRATION_MODE: invite (default) or open
Who may open Studioingress.admin.allowCidrs, or ingress.admin.public: trueSTUDIO_ALLOW_CIDRS
Studio address in emailsprovisioning.studioUrl (required)from --domain

Container apps

KubernetesSingle host .env
OnappHosting.enabled: trueAPP_HOSTING_ENABLED=true (init.sh --apps)
Parent domainappHosting.domainAPP_DOMAIN
SandboxappHosting.runtimeClass (default gvisor)APP_SANDBOX_RUNTIME: runsc or none
Edge allowed inappHosting.ingressFromNamespace, appHosting.ingressFromLabelsn/a
HTTPS per app / custom domainsappHosting.customDomains.enabled, .issuer.emailalways (the edge issues certificates)

Realtime

Every Postgres project gets a CDC watcher that reads its changes and publishes them to a shared NATS stream, which GraphQL subscriptions read. On Kubernetes the watcher is a pod in the project's namespace; on a single host it is a container named excalibase-<project>-watcher (under 30 MiB in use, capped at 256 MiB). On a single host NATS has no per-client login: only the watchers and the GraphQL service can reach it, over networks tenant databases and apps do not join.

The stream keeps changes for every project together until either limit is reached; the oldest go first.

KubernetesSingle host .env
How long changes are keptnats.cdcStream.maxAge (default 24h)CDC_STREAM_MAX_AGE (default 24h)
Most disk the stream usesnats.cdcStream.maxBytes (default 1073741824, 1 GiB)CDC_STREAM_MAX_BYTES (default 1073741824)

A stalled watcher holds back at most 20% of the project's storage size in WAL; past that Postgres drops the slot's backlog and the watcher starts again from the current position.

Features that ship off

Turn these on per install: features.mcp (MCP for AI coding tools), features.pipeline (deploy from your CI), features.appStorage (app users' file uploads). On Kubernetes:

helm upgrade platform-aio excalibase/platform-aio --version 1.5.1 -n excalibase-platform \
  --reset-then-reuse-values --set features.mcp=true

On a single host, set them in .env and recreate the containers:

echo FEATURE_MCP=true >> .env
docker compose up -d        # or: podman compose up -d

The single-host names are FEATURE_MCP and FEATURE_PIPELINE.

Images

The chart's version picks the images: chart 1.5.1 runs excalibase/*:1.5.1. On a single host, TAG in .env defaults to the release the bundle came with. Pin a release; never run latest or main.