Deploy and Host Stack Auth on Railway

Built for an LLM agent to deploy and use. There is no setup wizard and nothing to fill in: the server secret, the admin password and every database password are generated at deploy time, the admin user exists from the first boot, and the contract below lists every URL, variable name and the one script that proves it works.

Stack Auth is an open-source (MIT and AGPL) authentication platform: a user-management API with a ready-made dashboard, sign-in by password, magic link, OTP, passkey and OAuth, teams and permissions, plus SDKs for Next.js, React and plain REST. It is a self-hosted alternative to Auth0, Clerk and Supabase Auth. The project is also published under the name Hexclave; the same stackauth/server image carries both names.

About Hosting Stack Auth

This template runs three services: the official stackauth/server image (pinned by digest), Postgres 17 and ClickHouse 25.12, each with a volume. The Stack Auth service serves the dashboard and the API from one public domain: a small path router in the start command sends /api/* and /health to the backend and everything else to the dashboard, so only one URL is needed. On every boot it applies the database migrations and, only the first time, seeds the internal project and the admin user. The per-minute background jobs (email queue, external database sync, workflow engine) are called by the start command itself, authenticated with CRON_SECRET, because Railway has no cron for a long-running service. Allow about two minutes for the first deploy to turn healthy.

The first sign-in at the dashboard is the user admin@stack-auth.example.com with ADMIN_PASSWORD. Public sign-up on the dashboard project is switched off. No mail server or Svix webhook service is attached, so emails are not sent and webhooks are not delivered until you set the STACK_EMAIL_* and STACK_SVIX_* variables.

Agent contract

Public URL: https:// plus the RAILWAY_PUBLIC_DOMAIN of the stack-auth service, also published as the variable STACK_PUBLIC_URL; used below as STACK_URL. The dashboard is at /, the REST API at /api/latest.
Private URL: http://stack-auth.railway.internal:8102 (the backend API, for services in the same project)
Credentials: ADMIN_PASSWORD (user admin@stack-auth.example.com) and STACK_SERVER_SECRET. The internal project keys are derived from STACK_SERVER_SECRET, so they stay the same across redeploys as long as it does.
Auth: API clients send the headers x-stack-project-id: internal, x-stack-publishable-client-key: $PK and x-stack-access-type: client, plus x-stack-access-token: $ACCESS_TOKEN once signed in. PK is base64(HMAC-SHA256(key=STACK_SERVER_SECRET, message="internal-project-publishable-client-key")); the script below computes it. The server key for x-stack-access-type: server is the same derivation with the message internal-project-secret-server-key, sent as x-stack-secret-server-key.
Health: GET /health returns 200 with no credentials

# run with STACK_URL, ADMIN_PASSWORD and STACK_SERVER_SECRET set
PK=$(printf '%s' internal-project-publishable-client-key | openssl dgst -sha256 -hmac "$STACK_SERVER_SECRET" -binary | base64 -w0)
H=(-H "x-stack-project-id: internal" -H "x-stack-publishable-client-key: $PK" -H "x-stack-access-type: client" -H "content-type: application/json")
curl -s -o /dev/null -w 'health %{http_code}\n' "$STACK_URL/health"
curl -s -o /dev/null -w 'dashboard %{http_code}\n' "$STACK_URL/"
curl -s -o /dev/null -w 'wrong-password %{http_code}\n' "${H[@]}" "$STACK_URL/api/latest/auth/password/sign-in" -d '{"email":"admin@stack-auth.example.com","password":"wrong-password-1"}'
AT=$(curl -s "${H[@]}" "$STACK_URL/api/latest/auth/password/sign-in" -d "{\"email\":\"admin@stack-auth.example.com\",\"password\":\"$ADMIN_PASSWORD\"}" | sed -n 's/.*"access_token":"\([^"]*\)".*/\1/p')
echo "token ${#AT} chars"
curl -s "${H[@]}" -H "x-stack-access-token: $AT" "$STACK_URL/api/latest/users/me" | grep -o '"primary_email":"[^"]*"'

A fresh deploy prints health 200, dashboard 200, wrong-password 400, a token length above zero and "primary_email":"admin@stack-auth.example.com". Create more projects and keys in the dashboard (STACK_URL), then point your app's SDK at STACK_URL as the API URL.

Why Deploy Stack Auth on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Stack Auth on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.

Agent-ready - generated secrets, a contract block and one working script; no wizard before the first sign-in.
One URL - dashboard and API share a domain, so a single STACK_PUBLIC_URL configures the SDKs.
Redeploy-safe - Postgres and ClickHouse sit on volumes, the seed runs once, and keys derive from one stable secret.
Background jobs included - email queue, database sync and workflow engine run without an external scheduler.
Pinned image - pinned by digest, so a redeploy never changes the server version underneath you.

Common Use Cases

Self-hosted user authentication - sign-up, sign-in, sessions and teams for your own app without per-user pricing.
Auth0 and Clerk replacement - keep users in your own Postgres instead of a vendor.
Authentication for AI agents and apps - an agent can create projects, keys and users over the REST API.

Dependencies for Stack Auth Hosting

Postgres 17 (users, projects, sessions) and ClickHouse 25.12 (analytics and event data), both included in this template.

Deployment Dependencies

hexclave/hexclave - upstream project (formerly stack-auth/stack-auth)
Stack Auth documentation - SDKs, REST API and self-hosting
stackauth/server on Docker Hub - the image this template runs