From ddc87876dd2c075987383452cce0532b00091f4d Mon Sep 17 00:00:00 2001
From: Ben Cherry <ben@livekit.io>
Date: Tue, 12 Aug 2025 23:22:58 -0700
Subject: [PATCH] Dockerfile

---
 Dockerfile | 45 +++++++++++++++++++++++++++++++++++----------
 1 file changed, 35 insertions(+), 10 deletions(-)

diff --git a/Dockerfile b/Dockerfile
index d37738b..ea04d8f 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -1,15 +1,18 @@
 # syntax=docker/dockerfile:1
 
+# Use the official UV Python base image with Python 3.11 on Debian Bookworm
+# UV is a fast Python package manager that provides better performance than pip
+# We use the slim variant to keep the image size smaller while still having essential tools
 ARG PYTHON_VERSION=3.11
-# Fast Python builds using uv on Debian bookworm-slim
 FROM ghcr.io/astral-sh/uv:python${PYTHON_VERSION}-bookworm-slim AS base
 
-ARG UID=10001
-
-# Ensures that logs are captured in realtime
+# Keeps Python from buffering stdout and stderr to avoid situations where
+# the application crashes without emitting any logs due to buffering.
 ENV PYTHONUNBUFFERED=1
 
-# Create unprivileged user
+# Create a non-privileged user that the app will run under.
+# See https://docs.docker.com/develop/develop-images/dockerfile_best-practices/#user
+ARG UID=10001
 RUN adduser \
     --disabled-password \
     --gecos "" \
@@ -18,26 +21,48 @@ RUN adduser \
     --uid "${UID}" \
     appuser
 
-# System build deps for common Python wheels
+# Install build dependencies required for Python packages with native extensions
+# gcc: C compiler needed for building Python packages with C extensions
+# python3-dev: Python development headers needed for compilation
+# We clean up the apt cache after installation to keep the image size down
 RUN apt-get update && apt-get install -y \
     gcc \
     python3-dev \
   && rm -rf /var/lib/apt/lists/*
 
+# Create a new directory for our application code
+# And set it as the working directory
 WORKDIR /app
 
-# Dependency install first for better caching
+# Copy just the dependency files first, for more efficient layer caching
 COPY pyproject.toml uv.lock ./
 RUN mkdir -p src
+
+# Install Python dependencies using UV's lock file
+# --locked ensures we use exact versions from uv.lock for reproducible builds
+# This creates a virtual environment and installs all dependencies
+# Ensure your uv.lock file is checked in for consistency across environments
 RUN uv sync --locked
 
-# Copy application code
+# Copy all remaining pplication files into the container
+# This includes source code, configuration files, and dependency specifications
+# (Excludes files specified in .dockerignore)
 COPY . .
+
+# Change ownership of all app files to the non-privileged user
+# This ensures the application can read/write files as needed
 RUN chown -R appuser:appuser /app
+
+# Switch to the non-privileged user for all subsequent operations
+# This improves security by not running as root
 USER appuser
 
-# Pre-download models/assets at build time
+# Pre-download any ML models or files the agent needs
+# This ensures the container is ready to run immediately without downloading
+# dependencies at runtime, which improves startup time and reliability
 RUN uv run src/agent.py download-files
 
-# Start the agent
+# Run the application using UV
+# UV will activate the virtual environment and run the agent.
+# The "start" command tells the worker to connect to LiveKit and begin waiting for jobs.
 CMD ["uv", "run", "src/agent.py", "start"]