diff --git a/README.md b/README.md index b0217c3..93ebded 100644 --- a/README.md +++ b/README.md @@ -46,7 +46,13 @@ issue `#5` (CRUD API implementation). ```bash python -m venv .venv + +# macOS/Linux/Git Bash source .venv/bin/activate + +# Windows PowerShell +.\.venv\Scripts\activate + pip install -r backend/requirements.txt ``` @@ -120,9 +126,16 @@ institutional context. 4. Write tests and run `pytest backend/tests` before opening a pull request. 5. Document behaviour changes in code docstrings or the project docs. +## Backend Setup and .env Guidance + +For a step-by-step setup including environment variable handling, see: +[`docs/backend-setup.md`](docs/backend-setup.md) + ## License -MIT, Apache +This project is distributed under the **MIT License**. +If additional licenses are introduced for specific subcomponents, they should be +declared explicitly with scope and rationale. ## Maintainers diff --git a/docs/backend-setup.md b/docs/backend-setup.md new file mode 100644 index 0000000..7ba1c9d --- /dev/null +++ b/docs/backend-setup.md @@ -0,0 +1,67 @@ +# Backend Setup Guide (.env and Local Run) + +This guide explains how to configure and run the backend service consistently. + +## 1. Prerequisites + +- Python 3.11+ +- `pip` +- Access to project repository + +## 2. Create and Activate Virtual Environment + +```bash +python -m venv .venv + +# macOS/Linux/Git Bash +source .venv/bin/activate + +# Windows PowerShell +.\.venv\Scripts\activate +``` + +## 3. Install Dependencies + +```bash +pip install -r backend/requirements.txt +``` + +## 4. Configure Environment Variables + +Create a `.env` file in the backend runtime context and define required values. +Use safe defaults for local development and never commit production secrets. + +Recommended minimum variables: + +```env +ENV=development +DEBUG=true +DATABASE_URL=sqlite:///./lifeline.db +SECRET_KEY=change-me-in-real-environments +``` + +If your deployment uses different settings (PostgreSQL, external services), override these values accordingly. + +## 5. Run API + +```bash +uvicorn backend.app.main:app --reload +``` + +## 6. Verify Setup + +1. Open API docs at `http://127.0.0.1:8000/docs` +2. Call a basic endpoint to confirm service health. +3. Run tests: + +```bash +pytest backend/tests +``` + +## 7. Common Pitfalls + +- Missing virtual environment activation +- Missing/incorrect `.env` values +- Dependency version drift between environments + +Use this checklist before opening pull requests that affect backend behavior.