Skip to content

Configuration Guide

Environment configuration using .env files.

Environment Files

The boilerplate uses automatic environment loading:

  • local.env - Local development (auto-loaded)
  • prod.env - Production (use ENV_FILE=prod.env)
  • local.env.example - Template with all variables

Quick Setup

Bash
1
2
3
4
5
6
7
8
9
# Create local.env from example
cp local.env.example local.env

# Edit with your values
# At minimum, update: secret_key, database settings

# For production
cp prod.env.example prod.env
# Update with production values

Environment Variables Reference

Required (All Tiers)

Environment:

Text Only
1
env=local  # or production

Database (PostgreSQL):

Text Only
1
2
3
4
5
6
db_username=craftyourstartup
db_password=craftyourstartup
db_host=localhost
db_port=54323
db_database=craftyourstartup
db_sslmode=require

Security:

Text Only
1
2
3
secret_key=dev-secret-key-change-in-production
algorithm=HS256
access_token_expire_minutes=10080  # 7 days

Application URLs:

Text Only
1
2
domain=http://localhost:5173
redirect_after_login=http://localhost:5173/dashboard

Optional (All Tiers)

Google OAuth:

Text Only
1
2
3
google_oauth2_client_id=your-client-id
google_oauth2_secret=your-secret
google_oauth2_redirect_uri=http://localhost:8020/api/auth/google_callback

Email (Mailchimp Transactional):

Text Only
1
2
3
4
mailchimp_api_key=your-key
from_email=noreply@localhost
from_name=CraftYourStartup Dev
support_email=support@localhost

Top G & AI Velocity Only

Stripe Payments:

Text Only
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# Test keys (development)
STRIPE_SECRET_KEY=sk_test_your_test_secret_key
STRIPE_PUBLISHABLE_KEY=pk_test_your_test_publishable_key
STRIPE_WEBHOOK_SECRET=whsec_your_test_webhook_secret

# Product price IDs (created by task payments:products-create)
STRIPE_PRICE_STARTER=price_test_placeholder
STRIPE_PRICE_PRO=price_test_placeholder
STRIPE_PRICE_PREMIUM_SUB=price_test_placeholder
STRIPE_PRICE_ENTERPRISE_SUB=price_test_placeholder

Note: Hustler tier doesn't need Stripe variables.

Local Development

Example local.env:

Text Only
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
# Environment
env=local

# Database (Docker Compose default)
db_username=craftyourstartup
db_password=craftyourstartup
db_host=localhost
db_port=54323
db_database=craftyourstartup
db_sslmode=require

# Security
secret_key=dev-secret-key-change-in-production
algorithm=HS256
access_token_expire_minutes=10080

# URLs
domain=http://localhost:5173
redirect_after_login=http://localhost:5173/dashboard

# Google OAuth (optional)
google_oauth2_client_id=
google_oauth2_secret=
google_oauth2_redirect_uri=http://localhost:8020/api/auth/google_callback

# Stripe (Top G+ only)
STRIPE_SECRET_KEY=sk_test_...
STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

# Email (optional)
mailchimp_api_key=
from_email=noreply@localhost
from_name=CraftYourStartup Dev
support_email=support@localhost

Production Setup

Example prod.env:

Text Only
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
# Environment
env=production

# Database (your production database)
db_host=your-db-host.amazonaws.com
db_port=5432
db_database=craftyourstartup_prod
db_username=prod_user
db_password=SECURE_PASSWORD_HERE
db_sslmode=require

# Security (MUST change!)
secret_key=GENERATE_SECURE_RANDOM_STRING_MIN_32_CHARS
algorithm=HS256
access_token_expire_minutes=30
jwt_cookie_name=jwt
reset_token_expire_hours=1

# URLs
domain=https://yourdomain.com
redirect_after_login=https://yourdomain.com/dashboard

# Stripe (Top G+ - use LIVE keys)
STRIPE_SECRET_KEY=sk_live_...
STRIPE_PUBLISHABLE_KEY=pk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_PRICE_STARTER=price_live_...
STRIPE_PRICE_PRO=price_live_...
STRIPE_PRICE_PREMIUM_SUB=price_live_...
STRIPE_PRICE_ENTERPRISE_SUB=price_live_...

# Email (production service)
mailchimp_api_key=your_production_key
[email protected]
from_name=Your Company
[email protected]

# OAuth
google_oauth2_client_id=your-prod-client-id
google_oauth2_secret=your-prod-secret
google_oauth2_redirect_uri=https://yourdomain.com/api/auth/google_callback

Variable Descriptions

Database

  • db_username - PostgreSQL username
  • db_password - PostgreSQL password
  • db_host - Database host (localhost or remote)
  • db_port - PostgreSQL port (54323 local, 5432 standard)
  • db_database - Database name
  • db_sslmode - SSL mode (require for production)

Security

  • secret_key - JWT signing key (32+ characters)
  • algorithm - JWT algorithm (HS256)
  • access_token_expire_minutes - Token expiration (10080 = 7 days)
  • jwt_cookie_name - Cookie name for JWT (default: jwt)
  • reset_token_expire_hours - Password reset token expiration

Application

  • env - Environment name (local, production)
  • domain - Application domain URL
  • redirect_after_login - Where to redirect after login

Google OAuth (Optional)

  • google_oauth2_client_id - From Google Cloud Console
  • google_oauth2_secret - From Google Cloud Console
  • google_oauth2_redirect_uri - Callback URL (must match console exactly)

Get credentials: Google Cloud Console

Stripe (Top G+ Only)

  • STRIPE_SECRET_KEY - Stripe secret key (sk_test_ or sk_live_)
  • STRIPE_PUBLISHABLE_KEY - Stripe public key (pk_test_ or pk_live_)
  • STRIPE_WEBHOOK_SECRET - Webhook signature verification (whsec_*)
  • STRIPE_PRICE_* - Product price IDs from Stripe

Get keys: Stripe Dashboard

Email (Optional)

  • mailchimp_api_key - Mailchimp Transactional API key
  • from_email - Sender email address
  • from_name - Sender name
  • support_email - Support contact email

Get key: Mailchimp Transactional

Configuration Loading

The boilerplate uses automatic environment loading:

Bash
1
2
3
4
5
6
# No manual sourcing needed!
task run-backend        # Auto-loads local.env
task db:migrate-up      # Auto-loads local.env

# For production
ENV_FILE=prod.env task run-backend

Verify Configuration

Bash
1
2
3
4
5
# Test configuration loading
task backend:config-test

# Show current config (sensitive data masked)
task backend:config-show

Security Best Practices

Development

  • Use test keys (Stripe test mode)
  • Weak passwords OK for local database
  • Development secret_key is fine

Production

  • Strong secret_key (generate: python -c "import secrets; print(secrets.token_urlsafe(32))")
  • Live Stripe keys (not test)
  • Secure database password
  • HTTPS URLs (domain should be https://)
  • Never commit prod.env to git

Secret Management

Production options:

  • Railway/Vercel environment variables
  • AWS Secrets Manager
  • Google Secret Manager
  • HashiCorp Vault

Common Issues

Configuration not loading:

Bash
1
2
3
4
5
# Verify file exists
ls -la local.env

# Check for syntax errors (no spaces around =)
cat local.env

Database connection fails:

Bash
1
2
3
4
# Verify PostgreSQL is running
docker ps | grep postgres

# Check db_* variables match Docker Compose settings

Stripe keys invalid:

Bash
1
2
3
# Verify keys start with correct prefix
# Test: sk_test_*, pk_test_*
# Live: sk_live_*, pk_live_*

Tier-Specific Notes

Hustler: Remove all STRIPE_* variables (not needed)
Top G+: Configure all Stripe variables for payments
AI Velocity: Same as Top G (all features)