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.

Local development

Setup

Clone the repository and check out the directory:

1git clone [email protected]: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 package. Copy all the .env.development files to .env.local in the respective packages for local development.

In a terminal, start the dependencies (Postgres and Inbucket) as Docker containers:

1docker compose -f dependencies.compose.yaml up

Then open a new terminal:

1pnpm install
2
3# Build everything once
4pnpm run build
5
6# Initialize the database and seed it with some data
7pnpm prisma db push
8pnpm prisma db seed
9
10# Run code generation (repeat this after e.g., changing the Prisma schema). This is part of the build script but faster.
11pnpm run codegen
12
13# Start the dev server
14pnpm run dev
15
16# In a different terminal, run tests in watch mode
17pnpm run test

You can now open the dashboard at http://localhost:8101, the API on port 8102, a demo on port 8103, docs on port 8104, Inbucket (emails) on port 8105, and Prisma Studio on port 8106.

Your IDE may show errors on all @stackframe/XYZ imports. To fix this, 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.

Database migrations

If you make changes to the Prisma schema, you need to run the following command to create a migration:

1pnpm run prisma migrate dev

Production deployment

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 [email protected]:stack-auth/stack.git
2cd stack

Set all the necessary environment variables (you can check out apps/backend/.env). Note that STACK_BASE_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 [email protected]:stack-auth/stack.git
2cd stack

Set all the necessary environment variables (you can check out apps/dashboard/.env). Note that NEXT_PUBLIC_STACK_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_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).