Deploy and Host Zitadel on Railway

Built for an LLM agent to deploy and use. There is no setup wizard and nothing to fill in: the admin password and the master key are generated at deploy time, an API service account is created on first boot, and its access token is printed to the deploy log. The contract below lists every URL, variable name and the one script that proves it works.

Zitadel is an open-source identity and access management server: OpenID Connect, OAuth 2.0, SAML 2.0 and SCIM sign-in, single sign-on, passkeys, multi-factor authentication, multi-tenant organizations and a complete gRPC and REST API. This template runs Zitadel together with a PostgreSQL database.

About Hosting Zitadel

This template runs two services. zitadel is the official ZITADEL v4.20.0 binary in a small Alpine wrapper image (pinned by digest, because the upstream image has no shell). The wrapper reads the public domain from Railway, waits for the database, and starts the stock server with the console login (Login V1) enabled, so one service serves the console, the sign-in pages and the API. On first boot it creates the instance, a console admin user from ZITADEL_ADMIN_PASSWORD, and an IAM_OWNER service account named railway-agent whose personal access token never expires. postgres is the official postgres:17 image (pinned by digest) with a volume at /var/lib/postgresql, reachable only on the private network.

All identity data lives in PostgreSQL. The zitadel volume at /zitadel-data holds only the service account token file. The admin password, master key and token are the same after every redeploy. Allow roughly two minutes for the first deploy to turn healthy.

Agent contract

Public URL: https:// plus the RAILWAY_PUBLIC_DOMAIN of the zitadel service, used as ZITADEL_URL. It serves the console at /ui/console, sign-in at /ui/login, OIDC at /.well-known/openid-configuration and the REST API under /management/v1, /admin/v1 and /v2.
Private URL: http://zitadel.railway.internal:8080
Credentials: console admin login name admin@zitadel.example.com with the password in ZITADEL_ADMIN_PASSWORD; API access token in the deploy log of the zitadel service as the line ZITADEL_API_PAT=... (printed on every boot). ZITADEL_MASTERKEY encrypts secrets in the database and must never change.
Auth: send Authorization: Bearer ZITADEL_API_PAT to the API
Health: GET /debug/healthz returns 200 with no credentials

# run with ZITADEL_URL, ZITADEL_API_PAT and ZITADEL_ADMIN_PASSWORD set; needs curl
H="Authorization: Bearer $ZITADEL_API_PAT"
curl -s -o /dev/null -w 'health %{http_code}\n' "$ZITADEL_URL/debug/healthz"
curl -s -o /dev/null -w 'anonymous %{http_code}\n' "$ZITADEL_URL/management/v1/orgs/me"
curl -fsS -H "$H" "$ZITADEL_URL/management/v1/orgs/me" | grep -o '"name":"ZITADEL"'
curl -fsS -H "$H" -H 'Content-Type: application/json' -d '{"name":"my-app"}' "$ZITADEL_URL/management/v1/projects" -o /dev/null -w 'create project %{http_code}\n'
curl -fsS -H "$H" -H 'Content-Type: application/json' -d "{\"checks\":{\"user\":{\"loginName\":\"admin@zitadel.example.com\"},\"password\":{\"password\":\"$ZITADEL_ADMIN_PASSWORD\"}}}" "$ZITADEL_URL/v2/sessions" -o /dev/null -w 'admin login %{http_code}\n'

A fresh deploy prints health 200, anonymous 401, "name":"ZITADEL", create project 200 and admin login 201. Create applications, users, roles and identity providers the same way, or open ZITADEL_URL/ui/console and sign in as the admin.

Why Deploy Zitadel 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 Zitadel 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 admin password, a service account token that never expires, a contract block and one working script; no setup wizard and no open first-user registration.
Stable credentials - the admin password, master key and token are the same after every redeploy.
State survives redeploys - users, organizations and applications live in PostgreSQL on a volume.
Private database - PostgreSQL has no public domain and is reached over the private network.

Common Use Cases

Authentication for your own product - OIDC and SAML sign-in, passkeys, MFA and social login for a web or mobile app, as an Auth0 or Keycloak alternative you host.
Agent-driven identity management - let an AI agent create projects, applications, users and roles through the REST API.
Single sign-on for internal tools - one login and role model in front of dashboards and self-hosted apps.

Dependencies for Zitadel Hosting

A PostgreSQL database (included in this template, volume at /var/lib/postgresql).

Deployment Dependencies

zitadel/zitadel - upstream project
Zitadel documentation - configuration and API reference