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
• Python Version
• Installing uv
• Getting Started
• Local Development
• Dependency Management
• Docker Compose
• Running Celery Worker
• Useful uv Commands
• Development Workflow
• 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.

Python 3.11.8

File	Setting
pyproject.toml	requires-python = ">=3.11,<3.12"
.python-version	3.11.8

Verify:

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 -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Close and reopen PowerShell, then verify:

uv --version

macOS / Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Restart the terminal and verify:

uv --version

---

Getting Started

# 1. Clone the repository
git clone <repository-url>
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

uv sync

Run the application

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:

uv run python manage.py migrate --env local

Test Environment:

uv run python manage.py migrate --env test

Production Environment:

uv run python manage.py migrate --env production

Or directly via Alembic (uses current environment variables):

uv run alembic upgrade head

2. Create a New Migration (Autogenerate from Models)

uv run alembic revision --autogenerate -m "your_migration_name"

3. Rollback the Last Migration

uv run alembic downgrade -1

4. Seed Database (By Environment)

Local:

uv run python manage.py seed --env local

Production:

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

uv add <package>

Examples:

uv add httpx
uv add "httpx==0.28.1"
uv add "pikepdf>=8.0.0,<11.0.0"

Add a development dependency

uv add --dev pytest
uv add --dev ruff
uv sync

Remove a dependency

uv remove <package>
uv sync

Upgrade dependencies

Single package:

uv lock --upgrade-package <package>
uv sync

Example:

uv lock --upgrade-package fastapi
uv sync

Specific version:

uv add "fastapi==0.116.1"

All packages (use only for deliberate maintenance):

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

# 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

# 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

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)

Remove-Item -Recurse -Force .venv
uv sync

Linux / macOS

rm -rf .venv
uv sync

Force reinstall

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 <package>	Add a production dependency
uv add --dev <package>	Add a development dependency
uv remove <package>	Remove a dependency
uv lock	Update the lockfile
uv lock --upgrade-package <pkg>	Upgrade one package
uv lock --upgrade	Upgrade all packages
uv tree	View dependency tree
uv pip show <package>	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

# Normal local development
uv sync
uv run python manage.py run --env local

# Add a package
uv add <package>

# Remove a package
uv remove <package>

# Upgrade one package
uv lock --upgrade-package <package>
uv sync

Before creating a pull request

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.*