Developer setup

How to be ready to expand the template to build your unique SaaS.

Environment Variables

All configuration is managed via environment variables. Copy .env.example to .env and configure:

Database

POSTGRES_SERVER=localhost
POSTGRES_PORT=5432
POSTGRES_DB=app
POSTGRES_USER=postgres
POSTGRES_PASSWORD=changethis

Authentication

JWT_SECRET_KEY=your-secret-key-here
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30
REFRESH_TOKEN_EXPIRE_DAYS=30

Email Service

EMAIL_SERVICE=fake  # or "resend"
RESEND_API_KEY=     # Required if EMAIL_SERVICE=resend

Stripe

STRIPE_SECRET_KEY=sk_test_...
STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

# Stripe Price IDs (monthly and annual for each plan)
STRIPE_PRICE_IDS='{"basic_monthly":"price_xxx","basic_annual":"price_yyy","pro_monthly":"price_aaa","pro_annual":"price_bbb","enterprise_monthly":"price_ccc","enterprise_annual":"price_ddd"}'

Initial Data

CREATE_INITIAL_DATA=true
[email protected]
FIRST_SUPERUSER_PASSWORD=changethis

Error Tracking (Optional)

SENTRY_DSN=https://...

Email Configuration

The application supports two email providers:

Fake Email Service (Development):

• Set EMAIL_SERVICE=fake

• Emails are logged to console

• No external service required

Resend (Production):

• Set EMAIL_SERVICE=resend

• Set RESEND_API_KEY=re_...

• Transactional email delivery

Stripe Configuration

1

Create Stripe Account

• Sign up at https://stripe.com

• Get API keys from Stripe Dashboard (Settings → API keys)

• Use test keys for development (sk_test_... and pk_test_...)

2

Create Products and Prices

For each subscription plan (Basic, Pro, Enterprise), create two prices in Stripe:

Monthly Price:

• Go to Products → Create Product

• Set product name (e.g., "Basic Plan")

• Create a recurring price with "Monthly" billing

• Note the Price ID (e.g., price_1234monthly)

Annual Price:

• In the same product, click "Add another price"

• Create a recurring price with "Yearly" billing

• Set price (typically 10 months worth for 20% discount)

• Note the Price ID (e.g., price_1234annual)

Repeat for all plans.

3

Configure Environment Variables

Update .env with your Stripe Price IDs:

STRIPE_PRICE_IDS='{
  "basic_monthly":"price_xxx",
  "basic_annual":"price_yyy",
  "pro_monthly":"price_aaa",
  "pro_annual":"price_bbb",
  "enterprise_monthly":"price_ccc",
  "enterprise_annual":"price_ddd"
}'

Pricing Strategy:

• Monthly prices are charged per month

• Annual prices are typically 10 months worth (20% discount)

• Example: $10/month → $120/year (or $100/year for 20% savings)

4

Configure Webhook Endpoint

Set up webhooks in Stripe Dashboard (Developers → Webhooks):

• URL: https://yourdomain.com/payments/webhooks/stripe

• Events to listen for:

  • customer.subscription.created

  • customer.subscription.updated

  • customer.subscription.deleted

  • invoice.payment_succeeded

  • invoice.payment_failed

• Copy the webhook signing secret to STRIPE_WEBHOOK_SECRET

5

Billing Interval Options

Users can choose between monthly and annual billing:

• Monthly: Charged every month at the monthly rate

• Annual: Charged once per year, displayed as monthly equivalent

  • Example: $96/year shown as "$8/month (billed $96 annually)"

• Users select their preferred interval before subscribing

Development Workflow

Initial Setup

# Complete setup with one command
make setup-full

# Or step by step:
make setup          # Basic setup
make setup-secrets  # Generate secure secrets

Daily Development

# Start development environment
make dev

# View logs
make logs

# Run tests
make test

# Format code
make format

# Lint code
make lint

Database Operations

# Create new migration
make migrate-create msg="add new field"

# Run migrations
make migrate

# Connect to database
make db-shell

# Reset database (warning: deletes all data)
docker compose exec db psql -U postgres -d app -c "DROP SCHEMA public CASCADE; CREATE SCHEMA public;"

Testing

# Run all tests with coverage
make test

# Run backend tests only
make test-backend-simple

# Run specific test file
uv run pytest app/tests/unit/iam/test_iam_endpoints.py -v

# Run specific test
uv run pytest app/tests/unit/iam/test_iam_endpoints.py::test_register_user -v

Code Quality

The project uses:

• mypy - Static type checking (strict mode)

• ruff - Fast Python linter and formatter

• pre-commit - Git hooks for automatic checks

# Run linting
make lint

# Format code
make format

# Run pre-commit hooks
uv run pre-commit run --all-files

Frontend Development

# Start frontend dev server (if not using Docker)
cd frontend
npm install
npm run dev

# Build for production
npm run build

# Run linting
npm run lint

Docker Commands

# Start services
docker compose up -d

# Watch mode (auto-reload on changes)
docker compose watch

# View logs
docker compose logs -f

# Stop services
docker compose down

# Rebuild containers
docker compose build --no-cache