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:

File	Purpose	What to edit
config/app.js	App brand, metadata, SEO	appName, appDescription, domainName, contactEmail
config/billing.js	Pricing plans & payment provider	dodo.products, stripe.plans, lemonsqueezy.plans
config/theme.js	App visual palette	theme: "light", accent colors
.env.local	Database toggles & API credentials	DB_PROVIDER, BILLING_PROVIDER, AUTH_GOOGLE_ID

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

---

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.