Cloud Deployment

Aileron is a set of standard Docker containers with no infrastructure-specific assumptions. It runs on any platform that supports containers and PostgreSQL.

Services

ServiceDockerfilePortDescription
servercore/server/Dockerfile8080API server and auth handler
enclavecmd/aileron-enclave/Dockerfile8443TEE enclave binary (optional, only for confidential computing)
uiui/Dockerfile3000SvelteKit management UI
docsdocs/Dockerfile80API documentation (Scalar)
PostgreSQL—5432Database (any managed Postgres 16+ works)

Domains

Each service needs a domain or URL. The auth domain points to the server service; it is not a separate service.

DomainPoints toPurpose
api.yourdomain.comserverAPI endpoints (/v1/*)
auth.yourdomain.comserverOAuth callbacks (/auth/*)
app.yourdomain.comuiManagement UI
docs.yourdomain.comdocsAPI documentation

Environment variables

Server service

VariableRequiredDefaultDescription
AILERON_DATABASE_URLYesPostgreSQL connection string
AILERON_JWT_SIGNING_KEYYesHMAC signing key for access tokens. Generate with openssl rand -hex 32
AILERON_JWT_ISSUERNoaileroniss claim in issued JWTs
AILERON_ACCESS_TOKEN_TTLNo15mAccess token lifetime
AILERON_REFRESH_TOKEN_TTLNo168hRefresh token lifetime (7 days)
AILERON_UI_REDIRECT_URLNo/Redirect destination after successful login
AILERON_AUTO_VERIFY_EMAILNofalseSkip email verification on signup. Never enable in production.
GOOGLE_CLIENT_IDNoGoogle OAuth 2.0 client ID
GOOGLE_CLIENT_SECRETNoGoogle OAuth 2.0 client secret
GITHUB_OAUTH_CLIENT_IDNoGitHub OAuth 2.0 client ID
GITHUB_OAUTH_CLIENT_SECRETNoGitHub OAuth 2.0 client secret
RESEND_API_KEYNoResend API key for sending verification emails. When unset, codes are printed to the log.
MAIL_FROMNo[email protected]Sender address for transactional emails (requires RESEND_API_KEY)
AILERON_KEK_SESSION_TTLNo24hHow long a verified vault passphrase session remains active
AILERON_ESCROW_TTLNo168hHow long auto-escrowed credentials persist in TEE memory
AILERON_TEE_PROVIDERNo(empty)TEE provider: local (dev/test), confidential-space (production), or empty (disabled)
AILERON_ENCLAVE_URLNoBase URL of the enclave binary. Required when AILERON_TEE_PROVIDER=confidential-space
AILERON_ENCLAVE_IMAGE_DIGESTNoExpected container image digest (sha256:...) for attestation verification
AILERON_GCP_PROJECT_IDNoExpected GCP project ID for attestation verification

UI service

VariableRequiredDefaultDescription
PUBLIC_API_BASEYeshttp://localhost:8080URL of the server service
PUBLIC_POSTHOG_KEYNoPostHog project API key (passed as Docker build arg)
PUBLIC_POSTHOG_HOSTNohttps://us.i.posthog.comPostHog ingest endpoint (passed as Docker build arg)

Docs service

No configuration required.

Setup steps

  1. Provision PostgreSQL. Any managed Postgres 16+ service works (AWS RDS, GCP Cloud SQL, Supabase, Neon, Railway, etc.).

  2. Build the container images:

    docker build -f core/server/Dockerfile -t your-registry/aileron-server .
docker build -f ui/Dockerfile -t your-registry/aileron-ui ui/
docker build -f docs/Dockerfile -t your-registry/aileron-docs docs/
docker build -f cmd/aileron-enclave/Dockerfile -t your-registry/aileron-enclave .  # optional

  3. Configure environment variables on each service as listed above.

  4. Configure domains. Point each domain to its service and provision TLS certificates.

  5. Deploy. The server entrypoint automatically runs Atlas schema migrations against AILERON_DATABASE_URL before starting. Migrations are declarative and idempotent.

  6. Configure OAuth providers (optional, each is independent):

    Google (in the Google Cloud Console):

    • Create an OAuth 2.0 Client ID (Web application type)
    • Add https://auth.yourdomain.com/auth/google/callback as an authorized redirect URI

    GitHub (in GitHub Developer Settings):

    • Create a new OAuth App
    • Set the authorization callback URL to https://auth.yourdomain.com/auth/github/callback

  7. Verify:

    curl https://api.yourdomain.com/v1/health

Authentication

Authentication is opt-in. When no database is configured, the server runs without auth (suitable for local development).

When AILERON_DATABASE_URL is set, the server enables:

  • Email/password signup with email verification
  • Google and GitHub OAuth sign-in (with Okta and SAML planned)
  • Enterprise account model (auto-created on first sign-in)
  • JWT-based session management with refresh token rotation
  • Cross-provider deduplication (same email resolves to the same account)