Getting Started¶

Prerequisites¶

• Docker and Docker Compose
• just command runner

Quick Start¶

Turva uses just as a command runner for common development tasks.

Install just:

# macOS
brew install just

# Linux
cargo install just

# Other platforms: https://github.com/casey/just#installation

Set up the j alias (optional but convenient):

just abbreviate-just
# or: j aj
source ~/.zshrc

Available commands:

just              # List all available commands
j sd              # Start development environment
j sd b            # Start development environment (with rebuild)
j sc              # Stop all containers

Development Workflow¶

1. Start the services:

j sd

This will: - Build Docker images (if needed) - Start PostgreSQL database - Start FastAPI backend (port 8000) - Start React frontend (port 5173) - Start Caddy reverse proxy (port 80/443)

1. Access the application:
2. Frontend: http://localhost
3. API: http://localhost/api/
4. Direct frontend: http://localhost:5173

5. Direct API: http://localhost:8000

6. View logs:

docker compose logs -f        # All services
docker compose logs -f api    # API only
docker compose logs -f frontend # Frontend only

1. Stop the services:

j sc

First-Time Setup¶

Database Initialization¶

On first run, the PostgreSQL database will be automatically initialized. If you need to reset the database:

docker compose down -v    # Remove volumes
j sd                       # Start fresh

Environment Variables¶

The API requires a .env file at api/.env. A template is provided:

cp api/.env.example api/.env  # If .env.example exists
# or manually create api/.env with required variables

Running Migrations¶

Database migrations are automatically applied on startup. To manually run migrations:

docker compose exec api alembic upgrade head

Development Tips¶

• Hot Reload: Both frontend (Vite) and backend (Uvicorn) support hot reloading
• Code Formatting:
• Python: cd api/src && ruff format .
• TypeScript: cd frontend && yarn format
• Linting:
• Python: cd api/src && ruff check .
• TypeScript: cd frontend && yarn lint
• Pre-commit Hooks: Install with pre-commit install to automatically check code quality before commits

Troubleshooting¶

Port Conflicts¶

If ports 80, 443, 5173, or 8000 are already in use, stop conflicting services or modify the ports in docker-compose.yml.

Database Connection Issues¶

Ensure the DB_HOST in api/.env is set to postgres (the Docker service name), not localhost.

Container Issues¶

Clean up and rebuild:

docker compose down -v
j sd b