datapsycho/uvr-base repository overview

⁠uvr-base: Python 3.12 + uv Base Image

A production-ready Docker base image for Python 3.12 uv-managed applications. Supports AWS Lambda, FastAPI/ASGI servers, and container deployments.

Quick Start:

docker pull datapsycho/uvr-base:3.12.1-bookworm

⁠Overview

datapsycho/uvr-base is a production-ready base image for Python 3.12 uv-managed applications. It provides:

• Python 3.12 on Debian 12 (bookworm)
• uv package manager (latest)
• Essential build tools (gcc, g++, cmake, git)
• Pre-configured environment variables for container optimization

⁠Pulling the Image

⁠Recommended: Semantic Version (3.12.1-bookworm)

For reproducible builds, always use the immutable semantic version tag:

docker pull datapsycho/uvr-base:3.12.1-bookworm

This ensures your image build is deterministic. The 3.12.1-bookworm tag is immutable and will never change.

⁠Moving Tag (latest)

For development and CI where automatic updates are acceptable:

docker pull datapsycho/uvr-base:latest

The latest tag always points to the newest build and should NOT be used in production.

⁠Using the Image in Your Dockerfile

⁠AWS Lambda Application

FROM datapsycho/uvr-base:3.12.1

WORKDIR /var/task

COPY pyproject.toml uv.lock README.md ./
COPY src/ ./src/

ENV UV_COMPILE_BYTECODE=1 \
    UV_NO_DEV=1

RUN uv pip install --no-cache --system .

ENTRYPOINT ["python", "-m", "awslambdaric"]
CMD ["myapp.handler.lambda_handler"]

⁠FastAPI Webapp Deployment (Gunicorn + Uvicorn Workers)

For multi-core web deployments on ECS Fargate or Azure App Service:

FROM datapsycho/uvr-base:3.12.1

WORKDIR /app

COPY pyproject.toml uv.lock README.md ./
COPY src/ ./src/

ENV UV_COMPILE_BYTECODE=1

RUN uv pip install --no-cache --system --group webapp .

EXPOSE 8000

# Start Gunicorn with Uvicorn workers
# Worker count is read from WORKERS env var
CMD ["gunicorn", "--config", "src/gunicorn.conf.py", "genailib.webapp:app"]

⁠Lambda Configuration Best Practices

Memory & Timeout Recommendations:

Lambda CPU Allocation (Memory ↔ vCPU):

• 256 MB = 0.09 vCPU (shared)
• 512 MB = 0.18 vCPU
• 1024 MB = 0.35 vCPU
• 1536 MB = 0.5 vCPU (half core)
• 1769 MB = 0.625 vCPU
• 3008 MB = 1.0 vCPU (full core)
• 5120 MB = 1.67 vCPU
• 10240 MB = 3.09 vCPU (proportional scaling)

💡 CPU Scaling Notes:

• Doubling memory ≈ 2x faster CPU execution (for CPU-bound tasks)
• Network I/O is consistent across all memory tiers
• Disk I/O (/tmp) scales with memory allocation
• Max 3.09 vCPU available at 10GB memory (hard limit)

• 1GB for 1s = $0.0000166667
• 2GB for 10s = $0.000333334
• Increasing memory reduces execution time (linear CPU scaling)
• Example: 2GB PDF processor at 0.4s/page → 2,200 pages/invocation within 900s timeout

Estimated Capacity:

• 50-page PDF: ~20s execution
• 100-page PDF: ~40s execution
• 500-page PDF: ~200s execution
• Max burst: ~2,200 pages per 15-min window (rate limits apply)

Cold Start Optimization:

• Use UV_COMPILE_BYTECODE=1 for ~2-3s faster startup
• Memory affects provisioning speed (higher memory = faster execution)
• EphemeralStorage: 512MB default (adjust if processing large files)

⁠Base Image Environment Variables

The base image sets these automatically:

⁠Webapp Deployment Environment Variables

When using Gunicorn + Uvicorn workers, configure with these environment variables:

Example ECS Fargate Task Definition:

{
  "environment": [
    { "name": "WORKERS", "value": "2" },
    { "name": "TIMEOUT", "value": "120" },
    { "name": "LOG_LEVEL", "value": "info" }
  ]
}

⁠Installation Methods

⁠Using uv (Recommended)

uv pip install .[webapp]   # Install with FastAPI, Gunicorn, Uvicorn
uv pip install .[lambda]   # Install with AWS Lambda runtime and PDF tools

⁠Using pip

pip install .[webapp]
pip install .[lambda]

⁠Best Practices

⁠1. Use --no-cache with uv

Reduces final image size:

RUN uv pip install --no-cache --system .

⁠2. Pin Dependencies in uv.lock

Always commit uv.lock for reproducible builds:

uv pip install -r requirements.txt  # Creates/updates uv.lock
git add uv.lock && git commit -m "chore: update dependencies"

⁠3. Install as System Python (No Venv)

Use --system flag for container deployments:

RUN uv pip install --system .

⁠4. Use Multi-Stage Builds for Larger Projects

FROM datapsycho/uvr-base:3.12.1-bookworm AS builder
WORKDIR /build
COPY . .
RUN uv pip install --no-cache --system .

FROM datapsycho/uvr-base:3.12.1-bookworm
WORKDIR /app
COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
COPY --from=builder /build/src ./src
CMD ["python", "-m", "myapp"]

⁠Image Size

• Base image: ~594 MB
• With typical dependencies: ~650-800 MB
• With precompiled bytecode (UV_COMPILE_BYTECODE=1): Minimal overhead

⁠Supported Python Packages

The base image includes system libraries for:

• Binary wheels (manylinux)
• Cryptography (libssl-dev, libffi-dev)
• C extensions (gcc, g++, cmake)
• Git-based dependencies (git)
• SSL/TLS (ca-certificates)

⁠Updates & Versioning

⁠Semantic Versioning

• 3.12.1-bookworm = Python 3.12, Debian 12, immutable release
• 3.12.2-bookworm = Future patch (Python 3.12)
• 3.13.0-bookworm = Future major (Python 3.13)

⁠Tag Lifecycle

• Semver tags (3.12.1): Immutable, permanently available
• Latest tag: Moves to newest release, may break builds if not pinned
• Old tags: Remain available indefinitely for reproducibility

⁠Troubleshooting

⁠"No space left on device" during RUN

Reduce build context or use .dockerignore:

.git/
.pytest_cache/
__pycache__/
*.pyc
.venv/
node_modules/

⁠Import errors after uv pip install

Ensure you're using --system flag:

RUN uv pip install --system .  # ✅ Correct
RUN uv pip install .           # ❌ Creates venv (breaks in containers)

⁠Slow builds with large dependency trees

Use UV_COMPILE_BYTECODE=1 in production images:

ENV UV_COMPILE_BYTECODE=1
RUN uv pip install --no-cache --system .

⁠Links

• GitLab Repository: https://gitlab.com/pyninja/aiengineering/uvr⁠
• Docker Hub: https://hub.docker.com/r/datapsycho/uvr-base⁠
• uv Documentation: https://docs.astral.sh/uv/⁠
• Python 3.12: https://www.python.org/downloads/release/python-3120/⁠