FAQ
Q: What databases does Cairn use?
PostgreSQL (primary — projects, users, permissions, secrets metadata), MongoDB (logs, metrics, deployment events, audit trail), Redis (sessions and cache). The API provisions all three on-demand for user projects.
Q: Do I need Kubernetes to use Cairn?
Not for local development — just Postgres, Mongo and Redis (Docker Compose is fine). For production, k3s (or any Kubernetes cluster) is required. The bootstrap installs k3s automatically.
Q: How does authentication work?
Users sign in with an email or username and a password, then a two-factor code if two-factor is on for their account (admins can require it for everyone). In production you can add OIDC/SSO from Settings → Authentication, and Cairn ships oauth2-proxy on-cluster so services that don't ship SSO in their OSS build (Portainer, MinIO) can still sit behind the same single sign-on.
Q: Where's the admin password?
There isn't one. The seeded admin is [email protected] and you sign in by typing that
email — no password to remember, no default to change. If you want to lock the
account down, add an OIDC provider and disable email-only auth in Settings.
Q: Can I use Cairn with my existing Kubernetes cluster?
Yes. Run the bootstrap with SKIP_K8S=true — it will use your existing kubectl
context instead of installing k3s.
Q: What's the difference between preset roles and custom roles?
Preset roles (admin, devops, tech_lead, developer, viewer) have fixed
permission sets. Custom roles let you pick individual permissions. When a user has
both, the effective permissions are the union of the preset role and the custom
role.
Q: How are secrets encrypted?
AES-256-GCM with a random IV per secret. The master key is the SECRETS_ENCRYPTION_KEY
env var (32 bytes hex — generate with openssl rand -hex 32). See
architecture/secrets-architecture.md.
Q: How long do preview environments last?
72 hours by default. The PreviewDecayScheduler runs every hour and terminates
expired previews. Preview URLs follow the format
https://{project-slug}-{sanitized-branch}.preview.{DOMAIN}.
Q: Can I use my own SMTP server?
Yes — pick "Custom SMTP" during bootstrap or configure SMTP_HOST, SMTP_USER,
SMTP_PASS in the environment. AWS SES, SendGrid and Mailgun are also first-class
options and get their own prompts.
Q: What file storage options are available?
Bundled MinIO (installed by the bootstrap) or any S3-compatible provider (real
AWS S3, Cloudflare R2, Backblaze B2). Configure via the bootstrap's Backup Storage
prompt or via the EXT_S3_* env vars.
Q: Where are secrets stored? Do I need an external secret manager?
No external secret manager is needed. Secrets are stored in the platform's built-in encrypted secrets store (AES-256-GCM with versioning, rollback and audit trail). Manage them from the Secrets page in the portal or through the secrets API.
Q: How do I reset the database in local dev?
DROP DATABASE platform;
CREATE DATABASE platform OWNER platform;
Then restart the API — it auto-syncs schema and re-seeds demo users.
Q: The portal says "User email not found. Run init-demo first." — what do I do?
The auto-seed didn't run (usually because the API started before Postgres was healthy). Run:
npm --prefix platform/api run seed:db
Q: Something in the bootstrap failed halfway. Do I have to start over?
No — the script is idempotent. Just re-run sudo ./bootstrap.sh and it resumes
from the failed phase. Completion state lives in /etc/platform/.bootstrap_state.
Q: Where do I find generated credentials after a server install?
/etc/platform/.env (mode 600, root only). Back it up immediately — losing it
means losing access to Postgres, Mongo, Redis, MinIO, ArgoCD, Grafana and
Portainer's local admin.