docs/dev/spec/QUICKSTART.md

SwiftOps Backend - Quick Start Guide

Get up and running in 5 minutes!

🚀 Quick Setup

1. Install Dependencies

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install packages
pip install -r requirements-dev.txt

2. Configure Environment

# Copy environment template
cp .env.example .env

# Edit .env and add your credentials:
# - DATABASE_URL (Supabase PostgreSQL URL)
# - SUPABASE_URL
# - SUPABASE_KEY
# - SECRET_KEY (generate with: openssl rand -hex 32)

3. Start Services

# Option A: Use Docker (Recommended)
docker-compose up -d

# Option B: Local PostgreSQL and Redis
# Make sure PostgreSQL and Redis are running locally

4. Initialize Database

# Create initial migration
alembic revision --autogenerate -m "Initial schema"

# Apply migrations
alembic upgrade head

# (Optional) Seed database with test data
python scripts/seed_database.py

5. Run the Application

# Start development server
uvicorn src.app.main:app --reload

# Server will start at http://localhost:8000
# API docs at http://localhost:8000/api/docs

✅ Verify Installation

Visit these URLs to confirm everything works:

• API Root: http://localhost:8000
• Health Check: http://localhost:8000/health
• API Documentation: http://localhost:8000/api/docs
• ReDoc: http://localhost:8000/api/redoc

🧪 Run Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=src/app

# Run specific test
pytest tests/unit/services/test_auth_service.py

🔧 Development Tools

# Format code
black src/ tests/

# Sort imports
isort src/ tests/

# Lint code
flake8 src/ tests/

# Type checking
mypy src/

📦 Docker Commands

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f api

# Stop services
docker-compose down

# Rebuild after code changes
docker-compose up -d --build

🎯 Next Steps

1. Read the Build Plan: docs/agent/COMPREHENSIVE_BUILD_PLAN.md
2. Check Project Status: PROJECT_STATUS.md
3. Start with Phase 1: Implement core models
4. Follow the checklist: Week-by-week implementation

🆘 Troubleshooting

Database Connection Error

# Check if PostgreSQL is running
docker-compose ps

# Check DATABASE_URL in .env
# Format: postgresql://user:password@host:port/database

Import Errors

# Make sure you're in the virtual environment
source venv/bin/activate

# Reinstall dependencies
pip install -r requirements-dev.txt

Alembic Migration Issues

# Reset migrations (CAUTION: Deletes all data)
alembic downgrade base
alembic upgrade head

# Or drop and recreate database
docker-compose down -v
docker-compose up -d

📚 Useful Commands

# Create new migration
alembic revision --autogenerate -m "Add new table"

# Apply migrations
alembic upgrade head

# Rollback one migration
alembic downgrade -1

# Start Celery worker
celery -A src.app.tasks.celery_app worker --loglevel=info

# Start Celery beat
celery -A src.app.tasks.celery_app beat --loglevel=info

# Monitor Celery with Flower
celery -A src.app.tasks.celery_app flower

🎉 You're Ready!

The project is fully scaffolded and ready for development. Start building! 🚀