# Docqube Backend **FastAPI backend application for Docqube** A modern, container-ready backend built with FastAPI, managed by **uv**, and orchestrated with **Docker Compose**. --- ## Table of Contents - [Requirements](#requirements) - [Python Version](#python-version) - [Installing uv](#installing-uv) - [Getting Started](#getting-started) - [Local Development](#local-development) - [Dependency Management](#dependency-management) - [Docker Compose](#docker-compose) - [Running Celery Worker](#running-celery-worker) - [Useful uv Commands](#useful-uv-commands) - [Development Workflow](#development-workflow) - [Source of Truth](#source-of-truth) --- ## Requirements | Tool | Version / Notes | |-------------------|--------------------------| | **Python** | `3.11.8` (strict) | | **uv** | Latest | | **Docker** | Docker Desktop / Engine | | **Docker Compose**| v2+ | --- ## Python Version This project is **locked to Python 3.11**. ```text Python 3.11.8 ``` | File | Setting | |-------------------|----------------------------------| | `pyproject.toml` | `requires-python = ">=3.11,<3.12"` | | `.python-version` | `3.11.8` | **Verify:** ```bash uv run python --version ``` > **Expected:** `Python 3.11.8` > Do **not** use Python 3.12+ unless compatibility has been fully verified and the project configuration intentionally updated. --- ## Installing uv ### Windows ```powershell powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" ``` Close and reopen PowerShell, then verify: ```powershell uv --version ``` ### macOS / Linux ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` Restart the terminal and verify: ```bash uv --version ``` --- ## Getting Started ```bash # 1. Clone the repository git clone cd docqube_backend # 2. Install all dependencies uv sync ``` `uv sync` will: - Create `.venv` automatically - Use Python 3.11 - Resolve dependencies from `pyproject.toml` - Install exact versions from `uv.lock` - Install Windows-specific packages when on Windows > You do **not** need to manually create or activate a virtual environment. --- ## Local Development ### Install dependencies ```bash uv sync ``` ### Run the application ```bash uv run python manage.py run --env local ``` The application starts with the local environment configuration (example: `http://127.0.0.1:20001`). Host and port are controlled by the application settings. --- ## Database Migrations & Seeding All database migrations and seeds are executed through `uv`: ### 1. Apply Migrations (By Environment) **Local Environment:** ```bash uv run python manage.py migrate --env local ``` **Test Environment:** ```bash uv run python manage.py migrate --env test ``` **Production Environment:** ```bash uv run python manage.py migrate --env production ``` *Or directly via Alembic (uses current environment variables):* ```bash uv run alembic upgrade head ``` ### 2. Create a New Migration (Autogenerate from Models) ```bash uv run alembic revision --autogenerate -m "your_migration_name" ``` ### 3. Rollback the Last Migration ```bash uv run alembic downgrade -1 ``` ### 4. Seed Database (By Environment) **Local:** ```bash uv run python manage.py seed --env local ``` **Production:** ```bash uv run python manage.py seed --env production ``` --- ## Dependency Management All Python dependencies are managed exclusively through: - `pyproject.toml` - `uv.lock` > **Do not** maintain a separate `requirements.txt`. ### Add a production dependency ```bash uv add ``` Examples: ```bash uv add httpx uv add "httpx==0.28.1" uv add "pikepdf>=8.0.0,<11.0.0" ``` ### Add a development dependency ```bash uv add --dev pytest uv add --dev ruff uv sync ``` ### Remove a dependency ```bash uv remove uv sync ``` ### Upgrade dependencies **Single package:** ```bash uv lock --upgrade-package uv sync ``` Example: ```bash uv lock --upgrade-package fastapi uv sync ``` **Specific version:** ```bash uv add "fastapi==0.116.1" ``` **All packages** (use only for deliberate maintenance): ```bash uv lock --upgrade uv sync ``` ### Lockfile `uv.lock` **must** be committed to Git. It guarantees identical dependency resolution across developer machines, CI, Docker, staging, and production. > **Never** edit `uv.lock` manually. ### Inspection commands ```bash # Full dependency tree uv tree # Find a package (Windows PowerShell) uv tree | Select-String pikepdf # Find a package (Linux / macOS) uv tree | grep pikepdf # Inspect an installed package uv pip show pikepdf uv pip show torch ``` --- ## Docker Compose ### Development environment ```bash # Start (build + run) docker compose -p docqube-development -f docker-compose.development.yml up -d --build # Follow logs docker compose -p docqube-development -f docker-compose.development.yml logs -f # Stop docker compose -p docqube-development -f docker-compose.development.yml down # Normal rebuild docker compose -p docqube-development -f docker-compose.development.yml up -d --build # Completely fresh build (no cache) docker compose -p docqube-development -f docker-compose.development.yml build --no-cache docker compose -p docqube-development -f docker-compose.development.yml up -d ``` --- ## Running Celery Worker ### Locally ```bash uv run celery -A app.tasks.celery_app:celery_app worker --loglevel=info ``` > The worker requires the correct Redis and environment configuration. ### Recreate the virtual environment If `.venv` becomes corrupted: **Windows (PowerShell)** ```powershell Remove-Item -Recurse -Force .venv uv sync ``` **Linux / macOS** ```bash rm -rf .venv uv sync ``` **Force reinstall** ```bash uv sync --reinstall ``` --- ## Useful uv Commands | Command | Description | |----------------------------------------------|-------------------------------------------| | `uv --version` | Check uv version | | `uv run python --version` | Check Python version | | `uv python find` | Locate the Python interpreter | | `uv sync` | Install / synchronize dependencies | | `uv add ` | Add a production dependency | | `uv add --dev ` | Add a development dependency | | `uv remove ` | Remove a dependency | | `uv lock` | Update the lockfile | | `uv lock --upgrade-package ` | Upgrade one package | | `uv lock --upgrade` | Upgrade all packages | | `uv tree` | View dependency tree | | `uv pip show ` | Inspect an installed package | | `uv run python` | Run Python inside the project environment | | `uv run python manage.py run --env local` | Run the application | --- ## Development Workflow ### New developer quick start 1. Clone the repository 2. Install `uv` 3. Run `uv sync` 4. Create the required environment file (e.g. `.env.development`) 5. Verify Python → `uv run python --version` → `Python 3.11.8` 6. Run locally **or** start the full stack with Docker Compose 7. Check services and view logs ### Day-to-day workflow ```bash # Normal local development uv sync uv run python manage.py run --env local # Add a package uv add # Remove a package uv remove # Upgrade one package uv lock --upgrade-package uv sync ``` ### Before creating a pull request ```bash uv sync uv run python --version uv run pytest docker compose -p docqube-development -f docker-compose.development.yml build docker compose -p docqube-development -f docker-compose.development.yml up -d ``` ### Important rules **Do** - Use `uv sync`, `uv add`, `uv remove`, `uv run` - Commit `pyproject.toml`, `uv.lock`, and `.python-version` - Use Docker Compose for the full containerized environment **Do not** - Use `pip install ...` - Manually create `env/` or `venv/` - Manually edit `uv.lock` - Commit `.venv/` or real `.env` files - Maintain a manually synchronized `requirements.txt` --- ## Source of Truth | Concern | Source of Truth | |--------------------------------|----------------------------| | Python version | `.python-version` | | Python dependencies | `pyproject.toml` | | Locked dependencies | `uv.lock` | | Python / Docker environment | `Dockerfile` | | Environment orchestration | `docker-compose.*.yml` | | Environment configuration | `.env.*` |