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.
- Use a cloud hosted Postgres or start a example Postgres database. Don’t use this setting in production:
-
Get the example environment file and modify it to your needs. See the full template here.
-
Run the Docker container:
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:
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:
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:
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:
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:
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:
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:
Initialize the database
You need to initialize the database with the following command with the backend environment variables set:
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:
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).