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
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.
| Provider | Kubernetes | Single host .env |
|---|---|---|
| Your SMTP relay | email.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 SES | email.provider: ses and a ses-creds Secret | EMAIL_PROVIDER=ses, SES_ACCESS_KEY_ID, SES_SECRET_ACCESS_KEY, SES_REGION |
| Resend | email.provider: resend and a resend-creds Secret (key api-key) | EMAIL_PROVIDER=resend, RESEND_API_KEY |
| None | email.provider: noop | leave 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.
| Kubernetes | Single host | |
|---|---|---|
| Turn on | objectStore.bundled.enabled: true with provisioning.backupCredentials.provider: sts | on by default |
| Where browsers open files | objectStore.bundled.publicUrl (served by the edge) | FILES_PUBLIC_URL (https://files.<domain>) |
| Size | objectStore.bundled.storage (default 50Gi) | the host's disk |
| Platform database backups | platformDb.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):
| Kubernetes | Single host .env | |
|---|---|---|
| Project backups | Secret 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 STS | BACKUP_DEFAULT_ACCESS_KEY_ID, BACKUP_DEFAULT_SECRET_ACCESS_KEY, BACKUP_DEFAULT_ENDPOINT, BACKUP_DEFAULT_BUCKET, BACKUP_DEFAULT_REGION |
| Customer files | Secret storage-creds (same keys), its own bucket and key, with a CORS rule allowing GET, PUT, HEAD | STORAGE_ACCESS_KEY_ID, STORAGE_SECRET_ACCESS_KEY, STORAGE_ENDPOINT, STORAGE_BUCKET, STORAGE_REGION |
| Platform database | platformDb.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:
| Mode | Key kept | After a restart | Kubernetes | Single host |
|---|---|---|---|---|
| Manual | nowhere on the server: you keep it | sealed until an admin unseals it | vault.unseal.provider: manual | ./init.sh ... --manual-unseal |
| AWS KMS | only a ciphertext under your KMS key | unseals itself | vault.unseal.provider: awskms, vault.unseal.awskms.keyArn, region, credentialsSecret | n/a |
| On the server | in a Secret / the control plane's volume | unseals itself | plaintext + 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
| Kubernetes | Single host .env | |
|---|---|---|
| Who may sign up | provisioning.registrationMode: open (default) or invite | REGISTRATION_MODE: invite (default) or open |
| Who may open Studio | ingress.admin.allowCidrs, or ingress.admin.public: true | STUDIO_ALLOW_CIDRS |
| Studio address in emails | provisioning.studioUrl (required) | from --domain |
Container apps
| Kubernetes | Single host .env | |
|---|---|---|
| On | appHosting.enabled: true | APP_HOSTING_ENABLED=true (init.sh --apps) |
| Parent domain | appHosting.domain | APP_DOMAIN |
| Sandbox | appHosting.runtimeClass (default gvisor) | APP_SANDBOX_RUNTIME: runsc or none |
| Edge allowed in | appHosting.ingressFromNamespace, appHosting.ingressFromLabels | n/a |
| HTTPS per app / custom domains | appHosting.customDomains.enabled, .issuer.email | always (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.
| Kubernetes | Single host .env | |
|---|---|---|
| How long changes are kept | nats.cdcStream.maxAge (default 24h) | CDC_STREAM_MAX_AGE (default 24h) |
| Most disk the stream uses | nats.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.