Self-Hosting

Self-host Stack Auth on your own server

Stack Auth is fully open-source and can be self-hosted on your own infrastructure. This guide will introduce each component of the project and how to set them up.

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!

Services

On a high level, Stack Auth is composed of the following services:

  • API backend: The core of Stack Auth, providing the REST API that the dashboard and your app connect to. This is what api.stack-auth.com provides.
  • Dashboard: The interface for managing users, teams, auth methods, etc. This is available at app.stack-auth.com.
  • Client SDK: An SDK used to connect your app to the Stack Auth API backend, wrapping API calls and providing easy-to-use interfaces. More details here.
  • Postgres database: Used to store all user data. We use Prisma as the ORM and manage the database schema migrations.
  • Svix: Used to send webhooks. Svix is open-source and can be self-hosted, but also offers a cloud hosted solution. More on Svix here
  • Email server: We use Inbucket as a local email server for development and a separate SMTP server for production. Any email service supporting SMTP will work.

Run with Docker

Stack Auth provides a pre-configured Docker image that bundles the dashboard and API backend into a single container. To complete the setup, you’ll need to provide your own PostgreSQL database, and optionally configure an email server and Svix instance for webhooks.

  1. Use a cloud hosted Postgres or start a example Postgres database. Don’t use this setting in production:
1docker run -d --name db -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=password -e POSTGRES_DB=stackframe -p 5432:5432 postgres:latest

  1. Get the example environment file and modify it to your needs. See the full template here.

  2. Run the Docker container:

1docker run --env-file <your-env-file.env> -p 8101:8101 -p 8102:8102 stackauth/server:latest

For M1 Mac users, you might need to add --platform linux/x86_64 to the docker run command.

For Linux users, you might need to add --add-host=host.docker.internal:host-gateway to the docker run command in order to connect to the local Postgres database.

Now you can open the dashboard at http://localhost:8101 and the API backend on port 8102.

Now, login with your admin account on the dashboard and follow the normal setup process. Add NEXT_PUBLIC_STACK_API_URL=https://your-backend-url.com to your app’s environment variables so that it connects to your API backend instead of the default Stack Auth API backend (https://api.stack-auth.com).

Local development

Setup

Clone the repository and check out the directory:

1git clone git@github.com:stack-auth/stack.git
2cd stack

Pre-populated .env files for the setup below are available and used by default in .env.development in each of the packages. (Note: If you’re creating a production build (eg. with pnpm run build), you must supply the environment variables manually.)

In a new terminal:

1pnpm install
2
3# Run build to build everything once
4pnpm run build:dev
5
6# reset & start the dependencies (DB, Inbucket, etc.) as Docker containers, seeding the DB with the Prisma schema
7pnpm run start-deps
8# pnpm run restart-deps
9# pnpm run stop-deps
10
11# Start the dev server
12pnpm run dev
13# For systems with limited resources, you can run a minimal development setup with just the backend and dashboard
14# pnpm run dev:basic
15
16# In a different terminal, run tests in watch mode
17pnpm run test

You can now open the dev launchpad at http://localhost:8100. From there, you can navigate to the dashboard at http://localhost:8101, API on port 8102, demo on port 8103, docs on port 8104, Inbucket (e-mails) on port 8105, and Prisma Studio on port 8106. See the dev launchpad for a list of all running services.

Your IDE may show an error on all @stackframe/XYZ imports. To fix this, simply restart the TypeScript language server; for example, in VSCode you can open the command palette (Ctrl+Shift+P) and run Developer: Reload Window or TypeScript: Restart TS server.

You can also open Prisma Studio to see the database interface and edit data directly:

1pnpm run prisma studio

Run individual services

Database, Svix, email

Deploy these services with your preferred platform. Copy the URLs/API keys—you’ll need them in the next step.

API backend

Clone the repository and check out the root directory:

1git clone git@github.com:stack-auth/stack.git
2cd stack

Set all the necessary environment variables (you can check out apps/backend/.env). Note that NEXT_PUBLIC_STACK_API_URL should be the URL of your deployed domain (e.g., https://your-backend-url.com).

Build and start the server:

1pnpm install
2pnpm build:backend
3pnpm start:backend

Dashboard

Clone the repository (if you are running it on a separate server, or skip this step if you are using the same server as the API backend) and check out the dashboard directory:

1git clone git@github.com:stack-auth/stack.git
2cd stack

Set all the necessary environment variables (you can check out apps/dashboard/.env). Note that NEXT_PUBLIC_STACK_API_URL should be the URL of your deployed backend (e.g., https://your-backend-url.com).

Build and start the server:

1pnpm install
2pnpm build:dashboard
3pnpm start:dashboard

Initialize the database

You need to initialize the database with the following command with the backend environment variables set:

1pnpm prisma migrate deploy

The database is still empty; you need to create a project with the ID “internal” used by the dashboard to authenticate itself. You can do this with the following command:

1pnpm prisma db seed

Now you can go to the dashboard (e.g., https://your-dashboard-url.com) and sign up for an account.

To manage your dashboard configs with this account, manually go into the database, find the user you just created, and add { managedProjectIds: ["internal"] } to the serverMetadata jsonb column.

Go back to the dashboard, refresh the page, and you should see the “Stack Dashboard” project. We recommend disabling new user sign-ups to your internal project to avoid unauthorized account and project creations.

Now, create a new project for your app and follow the normal setup process. Add NEXT_PUBLIC_STACK_API_URL=https://your-backend-url.com to your app’s environment variables so that it connects to your API backend instead of the default Stack Auth API backend (https://api.stack-auth.com).