Skip to content

Local Development Setup

Guide for setting up the local development environment.

Quick Start

Bash
1
2
3
4
5
6
7
8
9
# 1. Clone the repository
git clone https://github.com/talent-factory/subscribe-flow.git
cd subscribe-flow

# 2. Komplettes Setup (Docker, Dependencies, DB, Bootstrap-API-Key)
make setup

# 3. Entwicklungsumgebung starten (Backend + Frontend + Celery Worker)
make dev

Prerequisites

Software

Tool Version Purpose Installation
Python 3.13+ Backend runtime python.org
Bun 1.0+ Frontend runtime & package manager bun.sh
Docker 24+ PostgreSQL, Redis docker.com
uv 0.5+ Python package manager astral.sh/uv
Git 2.40+ Version control git-scm.com

Why Bun?

Bun was chosen as the JavaScript runtime because it has been strategically positioned in the AI tooling ecosystem since its acquisition by Anthropic.

macOS

Bash
1
2
3
4
5
6
7
# Homebrew
brew install python@3.13 docker uv git

# Bun
curl -fsSL https://bun.sh/install | bash
# or
brew install oven-sh/bun/bun

Linux (Ubuntu/Debian)

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# Python
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt install python3.13 python3.13-venv

# Docker
curl -fsSL https://get.docker.com | sh

# uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Bun
curl -fsSL https://bun.sh/install | bash

Windows

PowerShell
1
2
3
4
5
6
7
# With winget
winget install Python.Python.3.13
winget install Docker.DockerDesktop
winget install astral-sh.uv

# Bun
powershell -c "irm bun.sh/install.ps1 | iex"

Docker Services

docker-compose.yml

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
services:
  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: subscribeflow
      POSTGRES_USER: subscribeflow
      POSTGRES_PASSWORD: subscribeflow
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data

volumes:
  postgres_data:
  redis_data:

Commands

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
# Start services
docker compose up -d

# Check status
docker compose ps

# View logs
docker compose logs -f postgres
docker compose logs -f redis

# Stop services
docker compose down

# Remove with data
docker compose down -v

Python Environment

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
# Create virtual environment
uv venv

# Activate
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows

# All dependencies
uv sync --all-extras

# Production dependencies only
uv sync

# With specific extras
uv sync --extra dev --extra docs

Dependencies

Group Contents Installation
default FastAPI, SQLAlchemy, etc. uv sync
dev pytest, ruff, mypy uv sync --extra dev
docs mkdocs, material uv sync --extra docs

Frontend (Bun + Vite)

The frontend is located in apps/web/ and uses Bun as the JavaScript runtime.

Setup

Bash
1
2
3
4
5
6
7
cd apps/web

# Install dependencies
bun install

# Start development server
bun run dev

Commands

Command Description
bun install Install dependencies
bun run dev Start dev server (http://localhost:5173)
bun run build Create production build
bun run preview Test production build locally
bun run test Tests in watch mode
bun run test:run Run tests once
bun run lint Run ESLint

Why Bun?

Bun offers significant advantages over Node.js/npm:

Text Only
1
2
3
4
5
Performance comparison (175 packages):
┌──────────────────────────────────────────┐
│ npm install:  ████████████████████ 11.2s │
│ bun install:  ██                    0.8s │
└──────────────────────────────────────────┘

Additional advantages:

  • Native TypeScript support (no tsc required)
  • Faster dev server startup
  • Strategic position in the Anthropic ecosystem

Frontend Environment Variables

Bash
1
2
cd apps/web
cp .env.example .env
Bash
1
2
# apps/web/.env
VITE_API_URL=http://localhost:8000/api/v1

Environment Variables

Create .env

Bash
1
cp .env.example .env

Variables

Bash
 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
# Database
DATABASE_URL=postgresql+asyncpg://subscribeflow:subscribeflow@localhost:5432/subscribeflow

# Redis
REDIS_URL=redis://localhost:6379

# Security
SECRET_KEY=your-secret-key-here-min-32-chars
JWT_ALGORITHM=HS256
JWT_EXPIRE_MINUTES=60

# Resend
RESEND_API_KEY=re_test_xxxxx

# Default Send Domain (für E-Mail-Versand)
DEFAULT_SEND_DOMAIN=notifications.example.com

# Stripe Billing
STRIPE_SECRET_KEY=sk_test_xxxxx
STRIPE_WEBHOOK_SECRET=whsec_xxxxx
STRIPE_PRICE_STARTER=price_xxxxx
STRIPE_PRICE_PROFESSIONAL=price_xxxxx

# Magic Link Authentication
MAGIC_LINK_EXPIRE_MINUTES=15
SESSION_EXPIRE_DAYS=7
SESSION_COOKIE_DOMAIN=              # Leer lassen für lokale Entwicklung (Produktion: .subscribeflow.net)

# Debug
DEBUG=true
LOG_LEVEL=DEBUG

Celery Worker

Der Celery Worker verarbeitet Background Tasks (z.B. Resend Sync, Webhook-Delivery, E-Mail-Versand). make dev startet den Worker automatisch zusammen mit Backend und Frontend.

Bash
1
2
3
4
5
# Worker manuell starten (falls nötig)
uv run celery -A subscribeflow.worker worker --loglevel=info

# Worker-Status prüfen
uv run celery -A subscribeflow.worker inspect active

Database

Migrations

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# Run all migrations
uv run alembic upgrade head

# Current version
uv run alembic current

# View history
uv run alembic history

# Create new migration
uv run alembic revision --rev-id 003 -m "add_webhooks"

# Downgrade
uv run alembic downgrade -1

Direct Connection

Bash
1
2
3
4
5
# psql
psql postgresql://subscribeflow:subscribeflow@localhost:5432/subscribeflow

# With Docker
docker compose exec postgres psql -U subscribeflow

Starting the Server

Development

Bash
1
2
3
4
5
6
# Empfohlen: alles auf einmal starten
make dev

# Oder einzeln:
make backend    # Nur Backend (http://localhost:8000)
make frontend   # Nur Frontend (http://localhost:5173)

Manuell

Bash
1
2
3
4
5
# With auto-reload
uv run uvicorn subscribeflow.main:app --reload --host 0.0.0.0 --port 8000

# With debug logging
LOG_LEVEL=DEBUG uv run uvicorn subscribeflow.main:app --reload

URLs

Service URL
API http://localhost:8000
Swagger UI http://localhost:8000/docs
ReDoc http://localhost:8000/redoc
Health http://localhost:8000/health
Frontend http://localhost:5173

Tests

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# All tests
uv run pytest

# With coverage
uv run pytest --cov=subscribeflow --cov-report=html

# Parallel
uv run pytest -n auto

# Single test
uv run pytest tests/test_subscribers.py::test_create -v

# With output
uv run pytest -s

Code Quality

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Linting
uv run ruff check .

# Auto-fix
uv run ruff check . --fix

# Formatting
uv run ruff format .

# Type checking
uv run mypy src/

Documentation

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
# Dependencies
uv sync --extra docs

# Interne Dokumentation (lokaler Server)
make docs

# Public-Dokumentation (nur öffentliche Seiten)
make docs-public

# Build (für Verifikation)
make docs-build

# Manuell
uv run mkdocs serve
uv run mkdocs build

IDE Setup

VS Code

Recommended extensions:

  • Python (ms-python.python)
  • Ruff (charliermarsh.ruff)
  • Pylance (ms-python.vscode-pylance)

.vscode/settings.json:

JSON
1
2
3
4
5
6
7
8
{
  "python.defaultInterpreterPath": ".venv/bin/python",
  "[python]": {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "charliermarsh.ruff"
  },
  "ruff.lint.args": ["--config=pyproject.toml"]
}

PyCharm

  1. Settings > Project > Python Interpreter
  2. Add Interpreter > Existing
  3. Select .venv/bin/python

Troubleshooting

Port already in use
Bash
1
2
3
4
5
6
# Find port
lsof -i :5432
lsof -i :8000

# Kill process
kill -9 <PID>
Docker issues
Bash
1
2
3
4
5
6
# Restart containers
docker compose down
docker compose up -d

# Check logs
docker compose logs -f
Migration errors
Bash
1
2
3
4
5
6
# Check status
uv run alembic current

# Reset
uv run alembic downgrade base
uv run alembic upgrade head
Celery Worker startet nicht
Bash
1
2
3
4
5
# Redis läuft?
docker compose ps redis

# Worker-Logs prüfen
uv run celery -A subscribeflow.worker inspect ping