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.