Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.hexclave.com/llms.txt

Use this file to discover all available pages before exploring further.

If you self-host, YOU will be responsible for updating Stack Auth and its dependencies. Security patches, bug fixes, and new features require manual updates on your infrastructure. If you would like premium support to help with this, contact us.
Stack Auth is fully open-source and can be self-hosted on your own infrastructure. The supported production path is the stackauth/server Docker image, which runs the Stack Auth API backend and dashboard in one container.
If you are unsure whether you should self-host, here are some things to consider:
  • Complexity: Stack Auth is a complex project with many interdependent services. Self-hosting requires managing these services and ensuring they work together seamlessly.
  • Updates: Stack Auth is a rapidly evolving project with frequent feature and fix releases. Self-hosting requires you to manage updates and apply them timely.
  • Reliability: Self-hosting requires you to ensure the reliability of your infrastructure. Downtimes and outages can be costly to handle.
  • Security: Self-hosting requires ensuring the security of your infrastructure. A compromised service can affect your users.
For most users, we recommend using Stack Auth’s cloud hosted solution. However, if you understand the above challenges and are comfortable managing them, follow the instructions below to self-host!

​
What You Run

In production, plan for these components:
  • Stack Auth server: The Docker image that serves the API backend and dashboard. The API is what your application SDKs call. The dashboard is where you manage projects, users, auth methods, and app settings.
  • Postgres: Required. Stores Stack Auth data and is migrated by the server image on startup unless you disable migrations.
  • Cron scheduler: Required for production. Calls internal maintenance endpoints for email queue processing and database sync jobs.
  • Reverse proxy or load balancer: Required for a production deployment. Terminate HTTPS and route traffic to the API and dashboard ports.
  • Email provider: Required for production email flows such as magic links, verification, password reset, and invitations. Configure SMTP or use a provider integration from the dashboard.
  • Svix: Required only if you use webhooks. You can use Svix Cloud or self-host Svix.
  • S3-compatible storage: Required for features that store files or assets.
  • ClickHouse: Required for the supported Docker deployment path. The migration script creates ClickHouse databases, tables, views, users, grants, and row policies after Postgres migrations.
  • Freestyle and OpenRouter keys: Freestyle is required for custom, manual, or programmatic email sending. OpenRouter is optional and used by AI-assisted dashboard features.
For local app development, use Local Development or the Local Emulator. Do not use the production Docker guide as your day-to-day local development setup.

​
Deploy With Docker

​
1. Create Postgres and ClickHouse

Use a managed Postgres service for production. The server reads its database URL from STACK_DATABASE_CONNECTION_STRING. Use a managed ClickHouse service or your own ClickHouse cluster. The server reads its ClickHouse URL and credentials from STACK_CLICKHOUSE_URL, STACK_CLICKHOUSE_ADMIN_USER, STACK_CLICKHOUSE_ADMIN_PASSWORD, and STACK_CLICKHOUSE_EXTERNAL_PASSWORD, and the database name from STACK_CLICKHOUSE_DATABASE (defaults to default when unset—set it to match the database you use in ClickHouse). The ClickHouse admin user must be able to create databases, tables, views, users, grants, and row policies. The migration script creates the analytics_internal database, views in the configured database, and a limited external user used by analytics queries. For a quick non-production smoke test, you can run both databases locally:
Terminal
docker network create stack-auth

docker run -d \
  --name stack-auth-postgres \
  --network stack-auth \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=password \
  -e POSTGRES_DB=stackframe \
  -p 5432:5432 \
  postgres:latest

docker run -d \
  --name stack-auth-clickhouse \
  --network stack-auth \
  -e CLICKHOUSE_DB=analytics \
  -e CLICKHOUSE_USER=stackframe \
  -e CLICKHOUSE_PASSWORD=password \
  -e CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1 \
  -p 8123:8123 \
  clickhouse/clickhouse-server:25.10
Set STACK_CLICKHOUSE_DATABASE to the same logical database your ClickHouse server uses (for this smoke test, CLICKHOUSE_DB=analytics and STACK_CLICKHOUSE_DATABASE=analytics). If you omit STACK_CLICKHOUSE_DATABASE, the backend defaults to default and will not match a container created only with CLICKHOUSE_DB=analytics. Do not use the example passwords, open ports, or single-node database layout for production.

​
2. Create an Environment File

Start from the server environment template, then fill in your production values. At minimum, set:
stack-auth.env
NEXT_PUBLIC_STACK_API_URL=https://auth-api.example.com
NEXT_PUBLIC_STACK_DASHBOARD_URL=https://auth.example.com

STACK_DATABASE_CONNECTION_STRING=postgresql://postgres:password@stack-auth-postgres:5432/stackframe
STACK_SERVER_SECRET=replace-with-a-32-byte-base64url-secret
CRON_SECRET=replace-with-a-long-random-secret

STACK_CLICKHOUSE_URL=http://stack-auth-clickhouse:8123
STACK_CLICKHOUSE_DATABASE=analytics
STACK_CLICKHOUSE_ADMIN_USER=stackframe
STACK_CLICKHOUSE_ADMIN_PASSWORD=password
STACK_CLICKHOUSE_EXTERNAL_PASSWORD=replace-with-a-long-random-password

STACK_SEED_INTERNAL_PROJECT_PUBLISHABLE_CLIENT_KEY=replace-with-a-random-value
STACK_SEED_INTERNAL_PROJECT_SECRET_SERVER_KEY=replace-with-a-random-value
STACK_SEED_INTERNAL_PROJECT_SUPER_SECRET_ADMIN_KEY=replace-with-a-random-value

STACK_SEED_INTERNAL_PROJECT_USER_EMAIL=admin@example.com
STACK_SEED_INTERNAL_PROJECT_USER_PASSWORD=replace-with-a-long-random-password
STACK_SEED_INTERNAL_PROJECT_USER_INTERNAL_ACCESS=true
STACK_SEED_INTERNAL_PROJECT_SIGN_UP_ENABLED=false
Generate STACK_SERVER_SECRET with a stable, high-entropy value and keep it unchanged across deploys:
Terminal
openssl rand -base64 32 | tr '+/' '-_' | tr -d '='
Generate the three STACK_SEED_INTERNAL_PROJECT_*_KEY values with any stable random values, for example:
Terminal
openssl rand -hex 32
The Docker entrypoint can generate the internal project keys if they are missing, but setting stable values yourself avoids rotating the dashboard project’s keys on every fresh container start. Generate CRON_SECRET with a stable random value too. Your scheduler uses it to authenticate internal maintenance requests:
Terminal
openssl rand -hex 32

​
3. Run the Server

Run the Docker image with the environment file:
Terminal
docker run -d \
  --name stack-auth \
  --network stack-auth \
  --env-file stack-auth.env \
  -p 8101:8101 \
  -p 8102:8102 \
  stackauth/server:latest
The container starts two services:
ServiceContainer portPurpose
Dashboard8101Admin dashboard for Stack Auth projects
API backend8102API used by the dashboard and your applications
On startup, the image runs database migrations and the seed script by default. To separate migrations from application startup, run one deployment with STACK_RUN_MIGRATIONS=true and STACK_RUN_SEED_SCRIPT=true, then run steady-state application containers with: 
STACK_RUN_MIGRATIONS=false
STACK_RUN_SEED_SCRIPT=false
Do this only after migrations and seeding have completed successfully for the current image version.

​
4. Run Cron Jobs

The Docker image does not start cron jobs for you. In production, configure exactly one scheduler for each deployment environment to call these internal endpoints with the CRON_SECRET bearer token:
EndpointPurpose
/api/latest/internal/email-queue-stepProcesses queued emails.
/api/latest/internal/external-db-sync/sequencerSchedules external database sync work.
/api/latest/internal/external-db-sync/pollerPolls and advances external database sync work.
For example, a scheduler can run these requests every minute:
Scheduler
curl -fsS -H "Authorization: Bearer $CRON_SECRET" https://auth-api.example.com/api/latest/internal/email-queue-step
curl -fsS -H "Authorization: Bearer $CRON_SECRET" https://auth-api.example.com/api/latest/internal/external-db-sync/sequencer
curl -fsS -H "Authorization: Bearer $CRON_SECRET" https://auth-api.example.com/api/latest/internal/external-db-sync/poller
Use your deployment platform’s scheduler, Kubernetes CronJob, systemd timer, or another reliable cron service. If you run multiple application replicas, do not let every replica run its own scheduler against the same database.

​
5. Put It Behind HTTPS

Expose the dashboard and API through HTTPS with your reverse proxy or load balancer:
Public URLProxies to
https://auth.example.comdashboard port 8101
https://auth-api.example.comAPI backend port 8102
The public URLs must match NEXT_PUBLIC_STACK_DASHBOARD_URL and NEXT_PUBLIC_STACK_API_URL. The API URL must be reachable from browsers, your application servers, and the dashboard.
Keep NEXT_PUBLIC_STACK_API_URL as the browser-reachable API URL. In the bundled Docker image, the entrypoint sets the dashboard’s server-side API URL to the backend inside the same container, so most deployments should not set API split variables manually. If you run the API and dashboard as separate services outside the bundled image, the codebase also supports NEXT_PUBLIC_BROWSER_STACK_API_URL and NEXT_PUBLIC_SERVER_STACK_API_URL for advanced network layouts.

​
6. Sign In to the Dashboard

Open your dashboard URL and sign in with the seeded admin user from STACK_SEED_INTERNAL_PROJECT_USER_EMAIL and STACK_SEED_INTERNAL_PROJECT_USER_PASSWORD. After you have access, create a project for your application and follow the setup guide. For self-hosted projects, your app must also point the SDK at your API URL:
.env.local
NEXT_PUBLIC_STACK_API_URL=https://auth-api.example.com
STACK_API_URL=https://auth-api.example.com
Keep using the project ID, publishable client key, and secret server key shown in your self-hosted dashboard. Do not mix keys from Stack Auth Cloud with a self-hosted API URL.

​
Service Configuration

​
Email

Production auth flows need a real email provider. Configure Custom SMTP or Resend in the dashboard after first sign-in, or provide SMTP environment variables if you want default server-level email settings: 
STACK_EMAIL_HOST=smtp.example.com
STACK_EMAIL_PORT=587
STACK_EMAIL_USERNAME=...
STACK_EMAIL_PASSWORD=...
STACK_EMAIL_SENDER=noreply@example.com
STACK_EMAILABLE_API_KEY=disable_email_validation
Set STACK_EMAILABLE_API_KEY to an Emailable key if you want email validation. Use disable_email_validation only when you intentionally want to skip validation. The dashboard’s Managed Domain email flow is an operator-managed integration. It requires additional server-side provider credentials such as STACK_RESEND_API_KEY, STACK_DNSIMPLE_API_TOKEN, and STACK_DNSIMPLE_ACCOUNT_ID. If you do not operate that integration, use Custom SMTP or your own Resend API key instead.

​
Webhooks

If you use webhooks, configure Svix: 
STACK_SVIX_API_KEY=...
STACK_SVIX_SERVER_URL=
Leave STACK_SVIX_SERVER_URL empty when using Svix Cloud. Set it when you self-host Svix. If the browser and container need different Svix URLs, also set NEXT_PUBLIC_STACK_SVIX_SERVER_URL to the external URL.

​
S3-Compatible Storage

Configure S3-compatible storage for features that store assets: 
STACK_S3_ENDPOINT=https://s3.amazonaws.com
STACK_S3_PUBLIC_ENDPOINT=https://your-public-bucket-url.example.com
STACK_S3_REGION=us-east-1
STACK_S3_ACCESS_KEY_ID=...
STACK_S3_SECRET_ACCESS_KEY=...
STACK_S3_BUCKET=stack-storage
STACK_S3_PRIVATE_BUCKET=stack-storage-private

​
AI and Custom Code Features

Some dashboard AI features require OpenRouter: 
STACK_OPENROUTER_API_KEY=...
Custom, manual, and programmatic email sending requires Freestyle: 
STACK_FREESTYLE_API_KEY=...

​
Operations

​
Upgrades

Before upgrading:
  1. Back up Postgres and any configured object storage.
  2. Back up ClickHouse if you depend on analytics or external database sync data.
  3. Pull the new Docker image.
  4. Run the new image once with migrations enabled.
  5. Verify dashboard sign-in, project loading, cron jobs, email sending, and any webhook flows you use.
  6. Roll forward your application containers to the same image.
The server image runs migrations by default. If you run multiple replicas, use your deployment system to ensure migrations run once before scaling the new version.

​
Health Checks

After deploy, verify:
Terminal
curl https://auth-api.example.com/api/v1/internal/backend-urls
Also test a complete sign-up or sign-in flow from your application, because redirect domains, email delivery, cron jobs, and SDK environment variables are the most common deployment issues.

​
Common Issues

​
The Dashboard Cannot Reach the API

Check that NEXT_PUBLIC_STACK_API_URL is the public API URL and has no typo or unreachable internal hostname.

​
Redirects Fail

Add your application origin to the project’s allowed domains in the dashboard. OAuth providers also need callback URLs that point at your self-hosted API URL.

​
Emails Do Not Arrive

Check the email provider configuration, sender domain verification, and any provider logs. For development-only email testing, use the Local Emulator instead of a production self-host deployment.

​
You Cannot Access the Dashboard

If you did not seed an admin user, temporarily enable internal project sign-up and rerun the seed script by restarting a container with seeding enabled: 
STACK_SEED_INTERNAL_PROJECT_SIGN_UP_ENABLED=true
STACK_RUN_SEED_SCRIPT=true
After creating your admin account, disable sign-up again, restart with STACK_SEED_INTERNAL_PROJECT_SIGN_UP_ENABLED=false, and prefer a seeded admin user for future deployments.