Skip to content

docs: Add backend/README.md with virtualenv setup, annotated .env guide, and local run instructions #88

@Sir-Emress

Description

@Sir-Emress

Problem

LifeLine-ICT has no dedicated backend setup guide. Contributors who want to work on the
FastAPI backend must piece together instructions from the root README (if any exist).
There is also no explanation of environment variables or .env file usage, which is a
common blocker for first-time contributors.

Proposed Solution

Create backend/README.md covering:

Prerequisites:

  • Python 3.9+, pip, virtualenv, PostgreSQL 13+

Annotated Environment Variables (.env.example comments):

# Database connection string
DATABASE_URL=postgresql://user:password@localhost:5432/lifeline_db

# JWT signing secret — use a long random string in production
SECRET_KEY=your_secret_key_here

# Set to False in production
DEBUG=True

# Comma-separated allowed hostnames
ALLOWED_HOSTS=localhost,127.0.0.1

# Frontend origin for CORS
CORS_ORIGINS=http://localhost:3000

Setup — Linux/macOS:

cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
alembic upgrade head
uvicorn main:app --reload --port 8000

Setup — Windows:

cd backend
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
copy .env.example .env
alembic upgrade head
uvicorn main:app --reload --port 8000

Health Check Verification:

curl http://localhost:8000/health
# Expected: {"status": "ok"}

Troubleshooting table for common errors.

Also: link backend/README.md from the root README.md.

Why It Matters

Without clear virtualenv and migration instructions, developers waste time on environment
configuration errors that have nothing to do with the feature they are trying to contribute.

Acceptance Criteria

  • backend/README.md created with virtualenv, pip, and migration steps
  • .env.example variables are annotated with inline comments
  • Separate Linux/macOS and Windows setup sections
  • Health check verification step included
  • Troubleshooting table covers common errors
  • Root

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions