cookiecutter-ai-saas

Accounts and credentials to have ready before you generate anything. Skip whichever don't match the choices you're about to make.

• A VPS production only — Done: you have SSH root access to a fresh Debian-family host (Ubuntu LTS) and know its IP address.
• A domain name production only — Done: you own a domain and can add A/AAAA records for it.
• Google OAuth credentials Google sign-in — Done: a client ID and secret from Google Cloud Console → APIs & Services → Credentials.
• Microsoft Entra ID credentials Microsoft sign-in — Done: a client ID, secret, and tenant ID (blank is fine, for multi-tenant) from the Azure Portal → App registrations.
• A Resend API key magic link — Done: an API key from resend.com → API Keys.
• A Stripe account Stripe — Done: a publishable key and secret key from the Stripe Dashboard, and your plans already exist there as products and prices.
• An LLM provider credential — Done: whichever provider you'll choose at generation is ready — an API key for OpenAI, Anthropic or OpenRouter, or Ollama installed locally with a model already pulled.

From a generated project to the full stack answering on your own machine.

• Prerequisites installed — Done: node -v, python3 --version and docker compose version all run without error, matching the Node and Python versions you chose at generation.
• Project generated — Done: cookiecutter gh:CrimsonCowLabs/cookiecutter-ai-saas finished, and you're inside the generated project directory.
• Both env files created — Done: cp .env.example .env.local for the host (npm run dev, npm run db:migrate — these reach Postgres and Redis on localhost) and cp .env.example .env.docker.local for the containers (docker compose — these reach them by service name), with .env.docker.local's DATABASE_URL pointed at @postgres:5432 and REDIS_URL at redis://redis:6379 instead of localhost.
• NEXTAUTH_SECRET set — Done: the output of openssl rand -hex 32 is pasted into both env files.
• Auth credentials filled in Google/Microsoft sign-in — Done: GOOGLE_ID/GOOGLE_SECRET and/or the MICROSOFT_ENTRA_ID_* variables are set in both env files for whichever provider(s) you chose.
• Magic-link key filled in magic link — Done: RESEND_API_KEY is set in both env files.
• Stripe keys filled in Stripe — Done: STRIPE_PUBLIC_KEY and STRIPE_SECRET_KEY are set in both env files. (STRIPE_WEBHOOK_SECRET comes later, once there's a webhook endpoint to get one from.)
• LLM provider key filled in — Done: the variables for whichever provider you chose (OLLAMA_*, OPENAI_API_KEY, ANTHROPIC_API_KEY, or OPENROUTER_*) are set in both env files.
• Dependencies installed — Done: npm ci finished without error.
• Infrastructure running — Done: docker compose up -d is up, and docker compose ps shows postgres and redis healthy.
• Vector search confirmed pgvector — Done: docker compose config shows the postgres service running pgvector/pgvector:pg18, not plain postgres.
• First migration generated — Done: npm run db:generate created a migration file. The template ships none, so this runs once before there's anything to apply.
• Migration applied — Done: npm run db:migrate ran it with no errors.
• Dev server running — Done: npm run dev is up, and http://localhost:3000 loads in a browser.
• Worker running — Done: in workers/app, after pip install "poetry>=2.5,<3" && poetry install, python worker.py is running and logs that it's listening for jobs.
• DB writer running — Done: with .env.local exported into the shell (set -a && source .env.local && set +a), npm run worker:db-writer is running without error.

Taking a working local stack to a real URL a stranger can reach.

• DNS pointed at the host — Done: the domain's A (and AAAA, if used) record resolves to the VPS's IP — confirm with dig +short <your domain>.
• Host provisioned — Done: ansible-playbook -i ansible/inventory.ini ansible/provision.yml has run, and running it again reports zero changes.
• Secrets vaulted — Done: ansible/vault.yml holds every production secret — the NextAuth secret, the database password, OAuth, Stripe, Resend, your LLM provider, and backups — and has been encrypted with ansible-vault encrypt.
• Deployed — Done: ansible-playbook -i ansible/inventory.ini ansible/deploy.yml --ask-vault-pass finished — the DNS pre-flight passed, and migrations ran against the new release.
• TLS live — Done: the site answers on https://<your domain> with a valid certificate. Caddy gets this on its own, once DNS resolves.
• Production callback URLs registered Google/Microsoft sign-in — Done: each provider's console has https://<your domain>/api/auth/callback/<provider> registered, matching NEXTAUTH_URL in .env-production.
• Stripe webhook registered Stripe — Done: a webhook endpoint pointing at https://<your domain>/api/webhook/stripe exists in the Stripe Dashboard, and its signing secret is vault_stripe_webhook_secret in the vault.
• Backups scheduled — Done: ansible-playbook -i ansible/inventory.ini ansible/backup.yml has run, and at least one dump has completed and verified at the remote destination (opsctl backup triggers one on demand).
• Smoke test passed — Done: on the live URL you can sign in, reach the dashboard, and — if Stripe is on — complete a Stripe test-mode checkout.