Refine Docker config and env sample

app/backend/Dockerfile

@@ -1,99 +1,84 @@
 #
 # BACKEND DOCKERFILE
 #
-# This Dockerfile builds the container for the FastAPI backend application.
-# It uses a multi-stage build to create optimized images for both development
-# and production environments.
-#
-# Stages:
-# - `base`: Installs Python and poetry, the dependency manager.
-# - `builder`: Installs application dependencies into a virtual environment.
-# - `development`: A debug-friendly image with the full project and an
-#                  auto-reloading server.
-# - `production`: A minimal, optimized image for production deployment.
-#
-# For more details, see: ./docs/architecture.md
+# Multi-stage image for the FastAPI + LiveKit Agent backend using uv.
+# - production: smallest runtime image with gunicorn/uvicorn worker
+# - development: hot-reload friendly image with full toolchain
+# - builder: installs dependencies once for reuse across stages
 #
+# Keep dependency definitions aligned with docs/architecture.md.
 
-# ------------------------------------------------------------------------------
-#   1. Base Stage
-#      - Installs Python and Poetry.
-#      - Sets up a non-root user for security.
-# ------------------------------------------------------------------------------
-FROM python:3.11-slim as base
+FROM python:3.12-slim AS base
 
-# Set environment variables to prevent Python from writing .pyc files and to
-# ensure output is sent straight to the terminal without buffering.
-ENV PYTHONDONTWRITEBYTECODE=1
-ENV PYTHONUNBUFFERED=1
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    UV_PROJECT_ENVIRONMENT=/app/.venv \
+    UV_LINK_MODE=copy
 
-# Install Poetry, a modern dependency management tool for Python.
-# We use a specific version to ensure reproducible builds.
-RUN pip install "poetry==1.8.2"
-
-# Create a non-root user and group to run the application.
-# Running as a non-root user is a security best practice.
-RUN addgroup --system app && adduser --system --group app
-
-# ------------------------------------------------------------------------------
-#   2. Builder Stage
-#      - Copies project files and installs dependencies using Poetry.
-#      - Dependencies are installed into a virtual environment for isolation.
-# ------------------------------------------------------------------------------
-FROM base as builder
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        build-essential \
+        curl \
+        libpq-dev \
+    && rm -rf /var/lib/apt/lists/*
 
+RUN groupadd --system app && useradd --system --home /app --gid app app
 WORKDIR /app
 
-# Copy the dependency definition files.
-COPY poetry.lock pyproject.toml ./
-
-# Install dependencies into a virtual environment.
-# `--no-root` tells Poetry not to install the project package itself.
-# `--only main` installs only production dependencies.
-RUN poetry install --no-root --only main
+# Install uv globally so subsequent stages share the toolchain.
+RUN pip install --upgrade pip uv
 
 # ------------------------------------------------------------------------------
-#   3. Production Stage
-#      - Creates a minimal image for production.
-#      - Copies the virtual environment from the `builder` stage.
-#      - Copies the application code.
+# Builder: install prod dependencies into an in-project virtualenv
 # ------------------------------------------------------------------------------
-FROM base as production
+FROM base AS builder
 
-WORKDIR /app
-
-# Copy the virtual environment with production dependencies from the builder.
-COPY --from=builder /app/.venv /app/.venv
-# Copy the application source code.
 COPY . .
-
-# Activate the virtual environment.
-ENV PATH="/app/.venv/bin:$PATH"
-
-# Switch to the non-root user.
-USER app
-
-# The default command is specified in the docker-compose.yml file, allowing
-# it to be easily overridden (e.g., for running Gunicorn).
-EXPOSE 8000
+RUN test -f pyproject.toml || (echo "pyproject.toml is required for uv sync"; exit 1)
+RUN if [ -f uv.lock ]; then \
+      uv sync --frozen --no-dev --compile-bytecode; \
+    else \
+      uv sync --no-dev --compile-bytecode; \
+    fi
 
 # ------------------------------------------------------------------------------
-#   4. Development Stage
-#      - Sets up the environment for local development.
-#      - Installs all dependencies, including development tools.
+# Production: minimal runtime image with gunicorn as the entrypoint
 # ------------------------------------------------------------------------------
-FROM base as development
+FROM python:3.12-slim AS production
 
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends libpq5 \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN groupadd --system app && useradd --system --home /app --gid app app
 WORKDIR /app
 
-# Copy dependency definition files.
-COPY poetry.lock pyproject.toml ./
-
-# Install all dependencies, including development dependencies like pytest.
-RUN poetry install --no-root
-
-# Activate the virtual environment.
+COPY --from=builder --chown=app:app /app /app
 ENV PATH="/app/.venv/bin:$PATH"
 
-# The command is specified in docker-compose.yml to run uvicorn with --reload.
+USER app
+EXPOSE 8000
+CMD ["gunicorn", "-w", "4", "-k", "uvicorn.workers.UvicornWorker", "app.main:app", "--bind", "0.0.0.0:8000"]
+
+# ------------------------------------------------------------------------------
+# Development: includes dev dependencies and keeps uvicorn reload-friendly
+# ------------------------------------------------------------------------------
+FROM base AS development
+
+COPY . .
+RUN test -f pyproject.toml || (echo "pyproject.toml is required for uv sync"; exit 1)
+RUN if [ -f uv.lock ]; then \
+      uv sync --frozen --dev --compile-bytecode; \
+    else \
+      uv sync --dev --compile-bytecode; \
+    fi
+
+ENV PATH="/app/.venv/bin:$PATH"
+USER app
 EXPOSE 8000