427 lines
9.0 KiB
Markdown
427 lines
9.0 KiB
Markdown
# 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 <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
|
|
|
|
```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 <package>
|
|
```
|
|
|
|
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 <package>
|
|
uv sync
|
|
```
|
|
|
|
### Upgrade dependencies
|
|
|
|
**Single package:**
|
|
|
|
```bash
|
|
uv lock --upgrade-package <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 <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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```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.*` |
|
|
|
|
|