Get Started

BoringPush runs on SQLite by default with a production-grade local SSL reverse proxy (https://<app>.localhost).
No hosted database, no Stripe keys, and no cloud logins needed to see and test the entire application.

1. Fast Track (Human & Interactive)

# 1. Clone & install
git clone <your-repo> my-saas
cd my-saas
npm install

# 2. Run the interactive setup orchestrator
npm run setup

# 3. Start local development server
npm run dev

During npm run setup, you will be asked for:

• App Display Name (e.g. SupaSend)
• Production Domain (e.g. supasend.com)
• Support Email (e.g. [email protected])
• Local Domain (default: my-saas.localhost)

The script automatically generates local SSL certificates with mkcert, configures Nginx, maps /etc/hosts, and prepares your .env.local.

2. Autonomous AI Agent Protocol (Claude Code, Cursor, Antigravity)

When an autonomous coding agent downloads or clones this repository on behalf of a user, the agent must execute the following deterministic protocol:

Phase A: Non-Interactive Bootstrap

Run the setup script with --yes and optional configuration flags:

npm run setup -- --yes --name="Target App Name" --domain="appdomain.com" --email="[email protected]"

If no flags are passed, the script automatically uses the folder name as the app slug and default brand values. It detects non-TTY environments automatically.

Phase B: File Customization Map

Agents should configure the following files based on user prompts:

Phase C: Verification Gate

Every modification made by an agent must pass:

OPENSSL_CONF=/dev/null npm run lint
# MUST exit with 0 errors and 0 warnings

3. Operating System Prerequisites

macOS

The setup script uses Homebrew. If not already installed:

# Install mkcert and Nginx
brew install mkcert nss nginx

# Install local root CA into macOS keychain & Firefox
mkcert -install

Linux (Ubuntu / Debian)

# Install prerequisites
sudo apt-get update
sudo apt-get install -y nginx libnss3-tools curl

# Install mkcert (Linux binary)
curl -JLO "https://dl.filippo.io/mkcert/latest?for=linux/amd64"
chmod +x mkcert-v*-linux-amd64
sudo cp mkcert-v*-linux-amd64 /usr/local/bin/mkcert
mkcert -install

4. Local URLs & Ports

When npm run dev starts, you will see:

┌─────────────────────────────────────────────────────────────┐
│  ● BoringPush Dev Server                                   │
│                                                             │
│  🔒 HTTPS (SSL):    https://my-saas.localhost               │
│  ⚡ HTTP (Direct):  http://127.0.0.1:3000                   │
│  💳 Dodo Return:    https://my-saas.localhost/success       │
└─────────────────────────────────────────────────────────────┘

• https://my-saas.localhost: Primary secure development entry point with valid green-padlock SSL.
• http://localhost:3000: Raw Next.js Node dev server port.
• Payment Provider Redirects: Point your Stripe or Dodo Payments return URL to https://my-saas.localhost/success for local testing.

5. First Login & Dev Credentials (No OAuth Keys Needed)

When running locally in NODE_ENV=development, test accounts are pre-wired in libs/next-auth.js:

• [email protected]: Standard free user (hasAccess=false). Used to test onboarding and paywall locks.
• [email protected]: Pro lifetime customer (hasAccess=true). Used to test unlocked features, /dashboard/purchases, and collaborator flows.

6. Running with Docker (Alternative to Local Node/Nginx)

If the user prefers running in Docker without installing Node.js or Nginx on their host:

# Mode 1: App container only (SQLite mounted on named volume)
npm run docker:up
# or: docker compose up -d

# Mode 2: Full containerized stack (App + Nginx + SSL in Docker)
npm run docker:full
# or: docker compose --profile full up -d

# Stream logs
npm run docker:logs

# Tear down
npm run docker:down

Your first hour (the guided tour)

Server's running, browser's open. Don't wander — do this exact loop and you'll understand the whole machine by minute sixty:

1. Minutes 0–10: click everything. Home, boards, pricing, blog, docs. This site is the product — every page you touch is a component you'll ship. Notice the speed: that's SQLite microseconds, no network round-trips. This is what your users will feel.
2. Minutes 10–25: log in twice. First as [email protected] (free — click every locked thing and watch the gates hold), then [email protected] (access granted — same pages, open). You just tested the entire paywall without a single API key. Remember this pair; they'll be your test users for every feature you ever build.
3. Minutes 25–40: break something safely. Create a board, post, vote, delete. Then open db/app.db directly (sqlite3 db/app.db "SELECT * FROM post;") and see your rows sitting there in a file. That file-ness is the whole philosophy: your database is a thing you can copy, back up, and inspect — not a service you pray to.
4. Minutes 40–60: read three files. CONVENTIONS.md (the law), libs/paywall.js (the lock), one thin route like app/api/board/route.js (the pattern). Forty minutes of reading now saves forty hours of guessing later. Then start 02-project-structure with the map already half-drawn in your head.

When setup fights back (it will, once)

Ninety percent of setup failures are three culprits. Check in this order:

• Port 3000 busy. Something else (another Next app, a zombie dev server) holds it. Kill it or pass --port. If the dev banner shows but pages hang, it's almost always this.
• mkcert / SSL complaints. Browser says "not secure" on .localhost: the local CA isn't trusted. Re-run the cert step from section 3 and restart the browser completely (not just the tab — the whole browser; cert stores load at startup).
• /etc/hosts mapping missing. my-saas.localhost doesn't resolve: the setup script edits hosts (needs sudo once). If you skipped the sudo prompt, add the line manually — it's one line, the script prints exactly which.
• Wrong Node version. Use the version in .nvmrc (or latest LTS). Ancient Node gives cryptic build errors that look like broken code; it's never the code on a fresh clone.

Still stuck after those four? Delete node_modules, npm install, run setup again. Fresh clones don't have exotic problems — it's always environment. Trust the checklist order; don't improvise until all four are confirmed clean.

Next Steps

• Database selection: Switch between SQLite, MongoDB, or Supabase in 05-database.md.
• Payment rail selection: Switch between Dodo, Stripe, or LemonSqueezy in 06-payments.md.
• Building features: Follow the data-first workflow in 13-build-features.md.