Skip to content

Local Development Setup

This guide walks you through setting up a complete local development environment for the MenoTime API.

Prerequisites

Before you begin, ensure you have the following installed:

  • Python 3.11 or higher — Check with python3 --version
  • Docker — Install Docker Desktop
  • Docker Compose — Usually bundled with Docker Desktop
  • AWS CLI — Install AWS CLI v2
  • PostgreSQL client — brew install postgresql (macOS) or apt-get install postgresql-client (Linux)
  • Git — For cloning the repository

Step 1: Clone the Repository

Clone the MenoTime API repository:

git clone https://github.com/your-org/menotime-api.git
cd menotime-api

Verify the repository structure:

ls -la
# You should see: app/, tests/, docker-compose.yml, requirements.txt, etc.

Step 2: Set Up Python Virtual Environment

Create a virtual environment to isolate dependencies:

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Verify the virtual environment is active:

which python  # Should point to ./venv/bin/python

Step 3: Install Dependencies

Install all Python packages from requirements.txt:

pip install --upgrade pip setuptools wheel
pip install -r requirements.txt

This installs: - FastAPI and Uvicorn - SQLAlchemy and Alembic - psycopg2 (PostgreSQL driver) - Pydantic - Python-dotenv - Testing tools (pytest, pytest-asyncio) - And other dependencies

Verify installation:

pip list | grep -i fastapi

Step 4: Start PostgreSQL with Docker Compose

The docker-compose.yml file defines a local PostgreSQL service. Start it:

docker-compose up -d postgres

Verify the container is running:

docker-compose ps
# NAME      SERVICE    STATUS
# postgres  postgres   Up

Wait a few seconds for PostgreSQL to be ready, then test the connection:

psql -h localhost -U menotime -d menotime -c "SELECT 1;"
# Password: (check .env.local for POSTGRES_PASSWORD)

Step 5: Configure Environment Variables

Create a .env.local file in the repository root:

cp .env.example .env.local

Edit .env.local with these values for local development:

# Database
DATABASE_URL=postgresql://menotime:menotime_dev@localhost:5432/menotime
POSTGRES_USER=menotime
POSTGRES_PASSWORD=menotime_dev
POSTGRES_DB=menotime

# FastAPI
ENVIRONMENT=development
DEBUG=true
API_HOST=0.0.0.0
API_PORT=8000
SECRET_KEY=dev-secret-key-change-in-production

# AWS (use your dev AWS credentials)
AWS_REGION=us-west-1
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key

# Logging
LOG_LEVEL=DEBUG

Load environment variables in your shell:

export $(cat .env.local | xargs)

Or use a tool like python-dotenv (already installed) to load them in the app.

Step 6: Run Database Migrations

Initialize the database schema using Alembic:

alembic upgrade head

This applies all pending migrations to your local PostgreSQL database.

Verify migrations were applied:

alembic current
# 1234567890abc (head)

To see migration history:

alembic history --oneline

Step 7: Start the Development Server

Start the FastAPI application with Uvicorn:

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

The --reload flag automatically restarts the server when you modify code.

You should see output like:

INFO:     Uvicorn running on http://0.0.0.0:8000
INFO:     Application startup complete

Step 8: Verify the Installation

Test the health check endpoint:

curl http://localhost:8000/health
# {"status": "healthy", "timestamp": "2024-01-15T10:30:00Z"}

Visit the interactive API documentation:

http://localhost:8000/docs

This opens Swagger UI where you can explore and test all API endpoints.

Running Tests

Run the test suite to ensure everything works:

pytest
# or for verbose output:
pytest -v

# Run specific test file:
pytest tests/test_api.py

# Run with coverage:
pytest --cov=app --cov-report=html

Stopping Services

When you're done with development:

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

# Stop PostgreSQL container
docker-compose down

# Deactivate virtual environment
deactivate

Troubleshooting

Python version mismatch

python3.11 -m venv venv  # Explicitly use Python 3.11

PostgreSQL connection refused

# Ensure container is running and healthy
docker-compose ps

# Check logs
docker-compose logs postgres

# Restart the container
docker-compose restart postgres

Alembic migration fails

# Check migration status
alembic current

# See all migrations
alembic history --oneline

# Downgrade to previous migration if needed
alembic downgrade -1

Port 8000 already in use

# Use a different port
uvicorn app.main:app --reload --port 8001

Next Steps