Skip to main content

Installation

Install and configure the boilerplate — from zero to running in minutes.

Installation

Choose your path based on your environment and goals.

Quick Start (Recommended)

The fastest path to a running instance:

Linux / macOS / WSL:

git clone <YOUR_REPO_URL>
cd app
./setup.sh

Windows (PowerShell):

git clone <YOUR_REPO_URL>
cd app
.\setup.ps1

What the interactive setup handles automatically:

  1. Detects Docker availability
  2. Guides you through project name, auth, billing, and environment questions
  3. Generates .env with secure secrets
  4. Installs dependencies (pnpm install)
  5. Runs database migrations
  6. Starts services
  7. Prepares the admin setup flow

Automated Production Setup

Use on a clean VPS for a zero-prompt deploy:

./setup.sh --production --auto

Optional flags:

  • --config=.env.setup — preload answers from a file
  • --low-memory — optimize for 2–4 GB VPS
  • --local — force local (PM2) mode
  • --docker — force Docker mode

Manual Setup

1. Prepare Environment

cp .env.example .env
bash scripts/setup-secrets.sh

Edit .env and confirm key values:

  • APP_URL, BETTER_AUTH_URL, NEXT_PUBLIC_APP_URL must share the same origin
  • AUTH_SECRET — min 32 characters
  • DATABASE_URL — your PostgreSQL connection string
  • REDIS_URL / REDIS_QUEUE_URL — Redis connection strings

2. Install Dependencies

pnpm install

3. Start Infrastructure

Docker (recommended for development):

docker compose up -d postgres redis-cache redis-queue

Local services: Start PostgreSQL and Redis using your system service manager.

4. Run Migrations

pnpm migrate

5. Start the App

Local development:

pnpm dev

PM2 standalone:

pnpm build
pm2 start ecosystem.config.cjs --env production

Full Docker stack:

docker compose up -d

Post-Install Verification

pnpm doctor
bash scripts/health-check.sh

Then verify:

  1. Web app loads at your configured URL
  2. GET /health returns {"status":"ok"} from the API
  3. Admin setup flow is reachable at /admin/setup
  4. Your billing and email providers are configured correctly

Common First-Run Mistakes

  1. Running Docker without preparing .env first
  2. Leaving placeholder secrets in .env
  3. Forgetting INTERNAL_API_URL when SSR runs in containers
  4. Restarting standalone web with raw pm2 instead of the project scripts
  5. Expecting OAuth or billing to work without provider credentials

Next Steps