Self-hosting guide

Overview

Atlas is open source and designed to be self-hosted. This guide covers the recommended deployment topology and configuration.

Most users don’t need to self-host. The hosted version at atlas.rebuildingus.org is the easiest way to use Atlas. Self-hosting is for organizations that need full control over their data, want to run Atlas on their own infrastructure, or want to contribute to development.

Recommended topology

The simplest production setup is:

Vercel for the web app (app/)
A small VM for the API (api/) running in Docker
SQLite on a persistent volume for data storage

This is the architecture Atlas uses in production. It’s cost-effective, easy to operate, and works well for a single operator. Why this split:

Vercel handles the frontend well and gives you automatic deploys and rollbacks
The API uses SQLite and runs background discovery work, which is better suited to a persistent VM
This is usually cheaper and simpler than putting everything on one platform

Quick start

1. Clone the repository

git clone https://github.com/RebuildingAmerica/atlas.git
cd atlas

2. Run the bootstrap script

pnpm bootstrap

This creates your .env.production file, generates auth secrets, and sets up the initial configuration. Follow the prompts to fill in required values.

3. Configure Stripe billing

Atlas uses Stripe Checkout, Stripe Billing, coupons, and webhooks for Pro, Team, and Research Pass access. The bootstrap scripts create the canonical products, prices, discount coupons, and webhook endpoints, then write the generated Stripe catalog to the correct env files. Local development uses Stripe test mode. Keep Stripe’s webhook forwarder open while testing Checkout. The listener reads the local app origin from .env, defaults to https://atlas.localhost, and forwards Stripe billing events to /api/stripe/webhook:

pnpm setup:local
pnpm stripe:listen
pnpm stripe:verify:local

Hosted staging uses Stripe test mode and Vercel Preview env vars:

pnpm setup:staging --yes
pnpm stripe:verify:staging

Hosted production uses Stripe live mode and Vercel Production env vars:

STRIPE_API_KEY=rk_live_replace_me pnpm setup:prod --yes
STRIPE_API_KEY=rk_live_replace_me pnpm stripe:verify:prod

To create the live key, open Stripe Dashboard in Live mode, go to Developers > API keys > Restricted keys, create a key named Atlas Production Billing, set these permissions, reveal the key once, and run setup with that rk_live_... value:

Read: Accounts v2, shown by Stripe errors as Basic Business Contact Information (accounts_kyc_basic_read)
Write: Products, Prices, Coupons, Customers, Checkout Sessions, Webhook Endpoints

Accounts v2: Read lets bootstrap show the friendly Stripe account name. If the restricted-key UI does not expose that permission, bootstrap can continue after Stripe returns the account ID and you confirm it is the intended account. A live secret key also works, but restricted keys are the default production path. Stripe CLI OAuth keys are enough for local and staging checks, but production bootstrap should use a Dashboard-created live API key. Test-mode IDs cannot be used in production. The catalog is intentionally small: Pro, Team, Team Seat, and Research Pass. Discounts are Pro-only coupons. Verified students pay $12.80 every four months; independent creators and journalists get 50% off Pro monthly or annual billing. Team pricing stays the same for every organization. The verification commands check products, prices, coupon scope, hosted Vercel env presence, and hosted webhook endpoint drift. See the repository’s docs/deployment/stripe-billing.md runbook for the exact product catalog, discount policy, and verification commands.

4. Choose a deployment path

Vercel + Docker (recommended)
Docker full stack

Deploy the web app to Vercel:Create a Vercel project with these settings:

Setting	Value
Framework Preset	TanStack Start
Root Directory	`app`
Install Command	`pnpm install --frozen-lockfile`
Build Command	`pnpm run build`
Node Version	24

Set these environment variables in the Vercel dashboard:

ATLAS_PUBLIC_URL=https://your-atlas-domain.com
ATLAS_DOCS_URL=https://your-subdomain.mintlify.dev
ATLAS_SERVER_API_PROXY_TARGET=https://api.your-atlas-domain.com
ATLAS_AUTH_API_KEY_INTROSPECTION_URL=https://your-atlas-domain.com/api/auth/internal/api-key
ATLAS_AUTH_INTERNAL_SECRET=<from .env.production>
ATLAS_EMAIL_PROVIDER=resend
ATLAS_EMAIL_FROM=Atlas <hello@mail.your-atlas-domain.com>
ATLAS_EMAIL_RESEND_API_KEY=<your Resend API key>

pnpm setup:staging and pnpm setup:prod sync the Stripe billing variables to the linked Vercel project automatically.Deploy the API to your VM:

cp .env.production.example .env.production

Fill in .env.production, then start the API:

docker compose --env-file .env.production up -d --build atlas-api

Expose the API through your reverse proxy or load balancer, then point Vercel’s ATLAS_SERVER_API_PROXY_TARGET at the public API URL.

Run everything on one machine with Docker Compose:

cp .env.production.example .env.production

Fill in .env.production, then start the stack:

docker compose --env-file .env.production -f compose.yaml up -d --build

This starts three services:

app — TanStack Start web server
api — FastAPI API server
caddy — Reverse proxy on ports 80 and 443

Caddy routes requests automatically:

/api/auth/* goes to the app (Better Auth)
/api/* goes to the API
Everything else goes to the app

Set ATLAS_PUBLIC_URL=https://your-atlas-domain.com in your .env.production.

Environment variables

Required

Variable	Description
`ATLAS_PUBLIC_URL`	Public origin of your Atlas instance (e.g., `https://atlas.example.com`)
`ATLAS_AUTH_INTERNAL_SECRET`	Shared secret between app and API. Generated by `pnpm bootstrap`.
`ATLAS_AUTH_DB_PATH`	Path to Better Auth SQLite database. Must be on persistent storage.
`ATLAS_AUTH_JWT_AUDIENCES`	OAuth audience claim for JWT validation. Include the MCP resource first, e.g. `https://atlas.example.com/mcp`, and add a comma-separated API resource when direct REST OAuth access is exposed.
`DATABASE_URL`	Path to the API’s SQLite database. Must be on persistent storage.
`CORS_ORIGINS`	JSON array of allowed origins (e.g., `["https://atlas.example.com"]`)

Authentication

Variable	Description
`ATLAS_AUTH_API_KEY_INTROSPECTION_URL`	Internal URL for API key validation
`ATLAS_OPERATOR_ALLOWED_EMAILS`	Comma-separated bootstrap allowlist for first owners (optional)
`ATLAS_DEPLOY_MODE`	Set to `local` for single-user local operation (disables auth). Omit in production.

Email

Variable	Description
`ATLAS_EMAIL_PROVIDER`	`resend` for production, `capture` for local/test
`ATLAS_EMAIL_FROM`	Sender address for auth and transactional email
`ATLAS_EMAIL_RESEND_API_KEY`	Resend API key (when using `resend` provider)

Discovery

Variable	Description
`ANTHROPIC_API_KEY`	Required for the AI-powered discovery pipeline
`SEARCH_API_KEY`	API key for web search during source fetching

Persistent storage

Both SQLite databases (content and auth) must live on persistent storage that survives container restarts. In Docker, this means a named volume or a mounted host directory.

Backups

At minimum:

Copy or snapshot the SQLite files on a schedule
Store backups somewhere other than the VM itself
Test a restore into a fresh volume

If you skip the restore test, you don’t know whether your backup is useful.

Verification checklist

After every deployment, check these in order:

GET /health returns 200
The app loads and can list entities
An entity detail page loads correctly
Magic-link sign-in succeeds
API key creation succeeds and X-API-Key access works
Creating a discovery run succeeds
Restarting the API does not lose data

Adapting for other hosts

The Vercel + Docker topology maps to most hosting providers:

Component	Alternatives
Vercel (app)	Netlify, Cloudflare Pages, any Node.js host
Docker VM (API)	Railway, Fly.io, Render, any container host
Caddy (proxy)	Nginx, Traefik, cloud load balancers
SQLite (storage)	Keep SQLite on persistent disk; no external database required

The key requirements:

The app needs ATLAS_PUBLIC_URL and ATLAS_SERVER_API_PROXY_TARGET
The API needs DATABASE_URL pointing to persistent SQLite storage
Both services need the same ATLAS_AUTH_INTERNAL_SECRET
The API container must support long-running background tasks (discovery pipeline)

Serverless platforms (AWS Lambda, Vercel Functions) are not suitable for the API because discovery runs are long-lived background tasks. Use a persistent container or VM.

API

MCP and agents

Workspace access

Tutorials

Open source

Overview

Recommended topology

Quick start

1. Clone the repository

2. Run the bootstrap script

3. Configure Stripe billing

4. Choose a deployment path

Environment variables

Required

Authentication

Email

Discovery

Persistent storage

Backups

Verification checklist

Adapting for other hosts

What’s next

API guide

Contributing

​Overview

​Recommended topology

​Quick start

​1. Clone the repository

​2. Run the bootstrap script

​3. Configure Stripe billing

​4. Choose a deployment path

​Environment variables

​Required

​Authentication

​Email

​Discovery

​Persistent storage

​Backups

​Verification checklist

​Adapting for other hosts

​What’s next

API guide

Contributing

Overview

Recommended topology

Quick start

1. Clone the repository

2. Run the bootstrap script

3. Configure Stripe billing

4. Choose a deployment path

Environment variables

Required

Authentication

Email

Discovery

Persistent storage

Backups

Verification checklist

Adapting for other hosts

What’s next