Local Development¶

Full development setup when you need hot reload, debugging, or to run tests.

Prerequisites¶

• Python 3.11+
• Node.js 20+
• FFmpeg (for video processing)
• uv (Python package manager)
• Docker (for Postgres, Redis, RabbitMQ, MinIO)

Backend Setup¶

Start the infrastructure services only:

docker compose up -d db redis rabbitmq minio minio-setup

Install dependencies and run migrations:

cd backend
uv sync --all-extras
uv run alembic upgrade head

Start the API server with hot reload:

uv run uvicorn src.interfaces.main:app --reload --port 8000

In a separate terminal, start a worker (e.g., analysis):

uv run taskiq worker src.workers.analysis:analysis_broker --workers 1

Repeat for other workers as needed (render, download, proxy (src.workers.download:proxy_broker), asset_edit, email). Without workers, background jobs won't run.

Frontend Setup¶

cd frontend
npm install
npm run dev

Vite proxies /api requests to the backend, so you don't need to configure CORS locally. The dev server runs at http://localhost:3000.

Landing Page Setup¶

cd landing
npm install
npm run dev

The Astro dev server runs at http://localhost:4321.

Running Tests¶

cd backend

# All tests
uv run pytest tests/ -v

# Just unit tests (fast)
uv run pytest tests/unit/ -v

# Specific module
uv run pytest tests/unit/workers/analysis/ -v

# With coverage
uv run pytest --cov=src

Integration tests require a running database. The test fixtures create isolated schemas.

Linting & Type Checking¶

cd backend
uv run ruff check src tests       # Lint
uv run ruff format src             # Format
uv run mypy src --config-file pyproject.toml  # Type check

Common Issues¶

Workers not picking up tasks: Make sure RabbitMQ is running (docker compose up -d rabbitmq) and TASKIQ_BROKER_TYPE=rabbitmq + TASKIQ_RABBITMQ_HOST=localhost in .env (use rabbitmq for Docker, localhost for local). Redis is still needed for cache/sessions — check CACHE_REDIS_HOST points to localhost.

Workers crash-looping on startup: RabbitMQ takes a few seconds to become ready. Workers auto-recover — check logs with docker logs <worker-container> and wait for "Listening started".

FFmpeg not found: Install it with brew install ffmpeg (macOS) or apt install ffmpeg (Linux).

MinIO presigned URLs fail: The internal Docker URL differs from localhost. Check STORAGE_PUBLIC_ENDPOINT in settings.

Database connection refused: When running outside Docker, set POSTGRES_SERVER=localhost in .env (default is db).

Key Files¶

← Quickstart Environment Variables →