VODA Backend

This project contains the backend server for our Software Engineering course's term project Voda.

Table of Contents

• For Frontend Developers (Quick Start)
• For Backend Developers (Local Development)
• Environment Variables
• Useful Commands

---

For Frontend Developers (Quick Start)

If you just need to run the backend service without modifying it, follow these steps:

Prerequisites

• Docker and Docker Compose installed
• Git

Steps

1. Clone the repository

   git clone https://github.com/i-m-teapot/backend.git
   cd VodaBackend

2. Set up environment variables

   Copy the example environment file and fill in the required values:

   cp .env.example .env

   Edit .env and provide your credentials:

   • SECRET_KEY: A secure random string for JWT tokens
   • AWS_ACCESS_KEY_ID: Your AWS access key
   • AWS_SECRET_ACCESS_KEY: Your AWS secret key
   • AWS_S3_BUCKET_NAME: Your S3 bucket name
   • FIREBASE_CREDENTIALS: Your Firebase credentials JSON string

   ⚠️ Note: Other variables can remain as defaults in the .env.example

3. Start the entire stack

   docker compose up -d

   This will:

   • Start a PostgreSQL database on port 5555
   • Build and start the backend service on port 8000
   • Automatically run database migrations
   • Set up health checks

4. Verify the service is running

   # Check container status
   docker compose ps
   
   # View logs
   docker compose logs -f backend

   The API will be available at: http://localhost:8000

   📖 API Documentation: Visit http://localhost:8000/docs to access the interactive Swagger UI

5. Applying new changes (after pulling updates)

   When the backend codebase is updated (new commits merged), you need to rebuild and restart:

   # Stop the current services
   docker compose down
   
   # Pull the latest changes
   git pull
   
   # Rebuild and start with new changes
   docker compose up -d --build

   The --build flag ensures Docker rebuilds the image with the latest code changes.

6. Stop the services

   docker compose down

   To also remove the database volume (fresh start):

   docker compose down -v

---

For Backend Developers (Local Development)

For active backend development with hot-reload and debugging capabilities:

Prerequisites

• Python 3.12 or higher
• Docker and Docker Compose
• Git

Steps

1. Clone the repository

   git clone https://github.com/i-m-teapot/backend.git
   cd VodaBackend

2. Install Python and uv

   On Linux/macOS:

   # Install uv (Python package manager)
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # Verify installation
   uv --version

   On Windows:

   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

3. Set up environment variables

   cp .env.example .env

   Edit .env with your configuration. For local development, ensure:

   DATABASE_URL="postgresql+psycopg2://user:password@localhost:5432/database"
   ASYNC_DATABASE_URL="postgresql+asyncpg://user:password@localhost:5432/database"
   POSTGRES_PORT=5432

   The database credentials should match those in compose.dev.yaml (defaults: user/password/database)

4. Install project dependencies

   uv sync

   This will install all required packages from pyproject.toml

5. Start the development database

   docker compose -f compose.dev.yaml up -d

   This starts only the PostgreSQL database on port 5432 (or your configured POSTGRES_PORT)

6. Verify database is ready

   docker compose -f compose.dev.yaml ps
   docker compose -f compose.dev.yaml logs

7. Run database migrations

   uv run alembic upgrade head

   This applies all pending migrations to your database

8. Start the development server

   With hot-reload (recommended for development):

   uv run uvicorn main:app --reload

   Without hot-reload:

   uv run uvicorn main:app

   The API will be available at: http://localhost:8000

9. Making changes

   With --reload enabled, the server automatically restarts when you modify Python files.

Database Migrations

When you modify database models:

1. Create a new migration

   uv run alembic revision --autogenerate -m "description of changes"

2. Review the generated migration in alembic/versions/

3. Apply the migration

   uv run alembic upgrade head

4. Rollback if needed

   uv run alembic downgrade -1  # Go back one migration

Stopping Services

# Stop the database
docker compose -f compose.dev.yaml down

# Stop and remove database volume (fresh start)
docker compose -f compose.dev.yaml down -v

# Stop the Python server
# Press Ctrl+C in the terminal where uvicorn is running

---

Environment Variables

Variable	Description	Default	Required
SECRET_KEY	Secret key for JWT token generation	-	✅
ALGORITHM	JWT algorithm	HS256	❌
ACCESS_TOKEN_EXPIRE_MINUTES	JWT token expiration time	30	❌
DATABASE_URL	PostgreSQL connection URL (sync)	-	✅
ASYNC_DATABASE_URL	PostgreSQL connection URL (async)	-	✅
POSTGRES_PORT	PostgreSQL port for dev database	5432	❌
AWS_ACCESS_KEY_ID	AWS access key for S3	-	✅
AWS_SECRET_ACCESS_KEY	AWS secret key for S3	-	✅
AWS_REGION	AWS region	us-east-1	❌
AWS_S3_BUCKET_NAME	S3 bucket name	-	✅
AWS_S3_BASE_FOLDER	Base folder in S3 bucket	VODA	❌
FIREBASE_CREDENTIALS	Firebase credentials json content	-	✅

---

Useful Commands

Docker Compose Commands

# Full stack (frontend developers)
docker compose up -d              # Start services in background
docker compose up -d --build      # Rebuild and start (after code updates)
docker compose down               # Stop services
docker compose down -v            # Stop and remove volumes
docker compose ps                 # Check service status
docker compose logs -f backend    # Follow backend logs
docker compose logs -f postgres   # Follow database logs
docker compose restart backend    # Restart backend service

# Dev database only (backend developers)
docker compose -f compose.dev.yaml up -d
docker compose -f compose.dev.yaml down
docker compose -f compose.dev.yaml logs

Development Commands

# Package management
uv sync                           # Install/sync dependencies
uv add <package>                  # Add a new package
uv remove <package>               # Remove a package
uv lock                           # Update lock file

# Database migrations
uv run alembic upgrade head       # Apply all migrations
uv run alembic downgrade -1       # Rollback one migration
uv run alembic revision --autogenerate -m "message"  # Create migration
uv run alembic history            # Show migration history
uv run alembic current            # Show current migration

# Run server
uv run uvicorn main:app --reload  # With hot-reload
uv run uvicorn main:app --host 0.0.0.0 --port 8000  # Custom host/port

Troubleshooting

Port already in use:

# Check what's using port 5432
sudo lsof -i :5432
# Or use a different port in compose.dev.yaml

Database connection issues:

# Check if database is running
docker compose -f compose.dev.yaml ps

# Test connection
docker compose -f compose.dev.yaml exec db psql -U user -d database

Permission issues with uv:

# Ensure uv is in your PATH
export PATH="$HOME/.cargo/bin:$PATH"

---

Project Structure

.
├── alembic/              # Database migrations
├── Controllers/          # API route handlers
├── Domain/              # Database models
├── DTOs/                # Request/response schemas
├── Middleware/          # Custom middleware
├── Services/            # Business logic
├── Websocket/           # WebSocket handlers
├── main.py              # FastAPI application entry point
├── database.py          # Database configuration
├── config.py            # Application configuration
├── compose.yaml         # Full stack Docker Compose
├── compose.dev.yaml     # Development database only
├── Dockerfile           # Backend container definition
└── docker-entrypoint.sh # Container startup script

---

API Documentation

Once the server is running, visit:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc