Deploy and Host SuperTokens

Self-host SuperTokens on Railway — the open-source alternative to Auth0, Firebase Auth, and AWS Cognito that gives you production-grade authentication with zero vendor lock-in and no per-user fees. SuperTokens handles email/password login, social OAuth, passwordless magic links, session management, and MFA, all through a lightweight HTTP microservice that your backend SDK calls directly.

This Railway template deploys the full SuperTokens stack in one click: the SuperTokens Core service (https://hub.docker.com/r/supertokens/supertokens-postgresql) pre-wired to a Railway-managed PostgreSQL database over private networking. Your API key is auto-generated on deploy — no manual secret setup required.

Getting Started with SuperTokens on Railway

Once your deploy is live, verify the core is healthy by visiting https://.up.railway.app/hello — a Hello response confirms the database connection is working.

Next, install the backend SDK for your language (pip install "supertokens-python[fastapi]" for Python, npm install supertokens-node for Node.js) and call supertokens.init() with your Railway domain as connectionURI and the generated API_KEYS value as apiKey. From there, mount the SuperTokens middleware and your app immediately gains /auth/signup, /auth/signin, /auth/signout, and session refresh endpoints — no additional route code needed.

To add enterprise features like MFA or multi-tenancy, register at supertokens.com to get a license key and POST it to /ee/license on your running instance.

About Hosting SuperTokens

SuperTokens is an open-source authentication platform built around a stateless HTTP core microservice. Unlike Auth0 or Cognito, your backend sits between your frontend and SuperTokens — this architecture lets you customize every auth flow in your own language and framework without writing Java or navigating an admin console.

Key features:

• Email/password, social login (Google, GitHub, Apple, etc.), and passwordless (magic links / OTP) out of the box
• Secure session management with rotating refresh tokens and built-in anti-CSRF and anti-session-fixation protection
• Pre-built frontend UI components for React, with headless support for Vue, Angular, and mobile
• Backend SDKs for Node.js, Python, and Go
• Multi-tenancy and MFA available via paid add-ons or license keys
• User management dashboard at /auth/dashboard
• SOC 2 and GDPR certified

On Railway, SuperTokens Core communicates with PostgreSQL over Railway's private network — no traffic leaves Railway's internal infrastructure between the two services.

Why Deploy SuperTokens on Railway

Run SuperTokens on Railway without managing infrastructure, SSL, or Docker volumes:

• No volume management — SuperTokens Core is stateless; all auth data lives in Postgres
• Private networking between Core and Postgres out of the box — zero config, zero egress cost
• Auto-generated API key on every deploy via Railway's native secret generator
• Managed TLS and custom domains with one click
• One-click redeploys whenever you update your SuperTokens image tag

Common Use Cases

• SaaS products replacing Auth0 — teams hitting Auth0's per-MAU pricing at scale move to self-hosted SuperTokens and pay only for infrastructure
• B2B apps needing multi-tenancy — each customer org gets an isolated auth context using SuperTokens' multi-tenancy recipe
• Apps with strict data residency requirements — keeping user credentials inside your own Railway project satisfies GDPR and regional data laws
• Startups bootstrapping auth fast — pre-built UI components and Railway's one-click deploy ship a working login page in under an hour

Dependencies for SuperTokens

• SuperTokens Core — registry.supertokens.io/supertokens/supertokens-postgresql:latest (GitHub: supertokens/supertokens-core)
• PostgreSQL — Railway managed Postgres (minimum version 13.0 required)

Environment Variables Reference

> Note: POSTGRESQL_CONNECTION_URI must use the postgresql:// scheme. Using postgres:// causes a startup error.

Deployment Dependencies

• Runtime: Java 17 (bundled inside the Docker image — no separate JDK install needed)
• Database: PostgreSQL 13+ (Railway's managed Postgres satisfies this)
• GitHub: supertokens/supertokens-core
• Docker Image: registry.supertokens.io/supertokens/supertokens-postgresql
• Official Docs: supertokens.com/docs

SuperTokens vs Auth0 vs Keycloak

SuperTokens hits the middle ground: easier than Keycloak to customise, cheaper than Auth0 at scale, and fully self-hostable unlike either managed-only alternative.

Minimum Hardware Requirements for SuperTokens

SuperTokens Core itself requires very little memory — it's a single Java process. The majority of resource usage lives in PostgreSQL.

Self-Hosting SuperTokens

Docker (quickest path):

docker run -p 3567:3567 \
  -e POSTGRESQL_CONNECTION_URI="postgresql://user:pass@host:5432/supertokens" \
  -d registry.supertokens.io/supertokens/supertokens-postgresql:latest

Docker Compose (with bundled Postgres):

version: '3'
services:
  db:
    image: postgres:15
    environment:
      POSTGRES_USER: supertokens_user
      POSTGRES_PASSWORD: somePassword
      POSTGRES_DB: supertokens
    healthcheck:
      test: ['CMD', 'pg_isready', '-U', 'supertokens_user', '-d', 'supertokens']
      interval: 5s
      retries: 5

  supertokens:
    image: registry.supertokens.io/supertokens/supertokens-postgresql:latest
    depends_on:
      db:
        condition: service_healthy
    ports:
      - 3567:3567
    environment:
      POSTGRESQL_CONNECTION_URI: "postgresql://supertokens_user:somePassword@db:5432/supertokens"

Verify with: curl http://localhost:3567/hello

Is SuperTokens Free?

Self-hosting SuperTokens is 100% free with no user limits — the open-source core covers email/password login, social login, passwordless, and session management at any scale.

The managed cloud service (where SuperTokens hosts the Core for you) is free up to 5,000 MAUs, then $0.02 per MAU beyond that — significantly cheaper than Auth0 at scale. Paid add-ons include MFA ($0.02/MAU self-hosted, $0.01/MAU cloud), account linking, and multi-tenancy. On Railway, your only cost is the infrastructure — Postgres and the SuperTokens Core service compute.

FAQ

What is SuperTokens? SuperTokens is an open-source authentication and session management platform. It runs as a standalone HTTP microservice that your backend SDK connects to, handling sign-up, sign-in, password reset, OAuth social login, session lifecycle, and more.

What does this Railway template deploy? Two services: a Railway-managed PostgreSQL database and a SuperTokens Core container (supertokens-postgresql:latest). They communicate over Railway's private network. A public HTTPS domain is generated for the Core so your backend SDK can reach it.

Why does this template include PostgreSQL? SuperTokens Core is stateless — it stores all user accounts, sessions, tokens, and credentials in PostgreSQL. Without a connected database, the Core runs with an in-memory store only (data is lost on restart). PostgreSQL is required for production use.

Can I use SuperTokens in production on Railway? Yes. SuperTokens is SOC 2 certified and horizontally scalable. Companies run it at millions of daily active users. On Railway, you can scale the Core service up and add read replicas to Postgres as your traffic grows.

Does SuperTokens support social login (Google, GitHub, etc.)? Yes. Social/OAuth login is built in. Add the relevant provider config (client ID and secret) to your backend SDK's recipeList alongside emailpassword.init() — no changes to the Railway deployment are needed.

Do I need to run database migrations manually? No. SuperTokens automatically creates and manages all required tables on first boot, as long as the database user has CREATE TABLE permission (Railway's default Postgres user does).

Can I add MFA or multi-tenancy later? Yes, without redeploying. MFA and multi-tenancy are paid add-ons activated by a license key. Register at supertokens.com, get a key, and POST it to /ee/license on your running Railway instance.