Make some more updates to the dockerfiles (#646)

* Make some more updates to the dockerfiles

* node

* Update node.Dockerfile

* Update python.pip.Dockerfile

* Update python.uv.Dockerfile

* Add g++

Author: bcherry

pkg/agentfs/examples/node.Dockerfile

@@ -1,26 +1,77 @@
 # This is an example Dockerfile that builds a minimal container for running LK Agents
+# For more information on the build process, see https://docs.livekit.io/agents/ops/deployment/builds/
 # syntax=docker/dockerfile:1
-FROM node:20-slim AS base
 
-WORKDIR /app
+# Use the official Node.js v22 base image with Node.js 22.10.0
+# We use the slim variant to keep the image size smaller while still having essential tools
+ARG NODE_VERSION=22
+FROM node:${NODE_VERSION}-slim AS base
+
+# Configure pnpm installation directory and ensure it is on PATH
+ENV PNPM_HOME="/pnpm"
+ENV PATH="$PNPM_HOME:$PATH"
 
-RUN npm install -g [email protected]
+# Install required system packages and pnpm, then clean up the apt cache for a smaller image
+# ca-certificates: enables TLS/SSL for securely fetching dependencies and calling HTTPS services
+# --no-install-recommends keeps the image minimal
+RUN apt-get update -qq && apt-get install --no-install-recommends -y ca-certificates && rm -rf /var/lib/apt/lists/*
 
-# Throw away build stage to reduce size of final image
+# Pin pnpm version for reproducible builds
+RUN npm install -g [email protected]
+
+# Create a new directory for our application code
+# And set it as the working directory
+WORKDIR /app
+
+# Build stage
+# We use a multi-stage build to keep the runtime image minimal
 FROM base AS build
 
-RUN apt-get update -qq && apt-get install --no-install-recommends -y ca-certificates
-COPY --link . .
+# Copy just the dependency files first, for more efficient layer caching
+COPY package.json pnpm-lock.yaml ./
 
+# Install dependencies using pnpm
+# --frozen-lockfile ensures we use exact versions from pnpm-lock.yaml for reproducible builds
 RUN pnpm install --frozen-lockfile
+
+# Copy all remaining pplication files into the container
+# This includes source code, configuration files, and dependency specifications
+# (Excludes files specified in .dockerignore)
+COPY . .
+
+# Build the project
 RUN pnpm run build
 
-FROM base
+# Remove development-only dependencies to reduce the runtime image size
+RUN pnpm prune --prod
+
+# Create the runtime image
+FROM base AS runtime
+
+# 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 "" \
+    --home "/app" \
+    --shell "/sbin/nologin" \
+    --uid "${UID}" \
+    appuser
+
+# Copy built application and production dependencies from the build stage
 COPY --from=build /app /app
+
+# Copy system CA certificates to ensure HTTPS works correctly at runtime
 COPY --from=build /etc/ssl/certs /etc/ssl/certs
 
-# Start the server by default, this can be overwritten at runtime
-EXPOSE 8081
+# Ensure ownership of app files and drop privileges for better security
+RUN chown -R appuser:appuser /app
+USER appuser
 
-CMD [ "node", "./dist/agent.js", "start" ]
+# Set Node.js to production mode
+ENV NODE_ENV=production
 
+# Run the application
+# The "start" command tells the worker to connect to LiveKit and begin waiting for jobs.
+CMD [ "node", "./dist/agent.js", "start" ]

pkg/agentfs/examples/python.pip.Dockerfile

@@ -1,52 +1,70 @@
 # This is an example Dockerfile that builds a minimal container for running LK Agents
+# For more information on the build process, see https://docs.livekit.io/agents/ops/deployment/builds/
 # syntax=docker/dockerfile:1
-ARG PYTHON_VERSION=3.11.6
-FROM python:${PYTHON_VERSION}-slim
+
+# Use the official Python base image with Python 3.11
+# We use the slim variant to keep the image size smaller while still having essential tools
+ARG PYTHON_VERSION=3.11
+FROM python:${PYTHON_VERSION}-slim AS base
 
 # Keeps Python from buffering stdout and stderr to avoid situations where
 # the application crashes without emitting any logs due to buffering.
 ENV PYTHONUNBUFFERED=1
 
-# Define the program entrypoint file where your agent is started.
-ARG PROGRAM_MAIN="{{.ProgramMain}}"
+# Disable pip version check to speed up builds
+ENV PIP_DISABLE_PIP_VERSION_CHECK=1
 
 # 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 "" \
-    --home "/home/appuser" \
+    --home "/app" \
     --shell "/sbin/nologin" \
     --uid "${UID}" \
     appuser
 
-
-# Install gcc and other build dependencies.
-RUN apt-get update && \
-    apt-get install -y \
+# Install build dependencies required for Python packages with native extensions
+# gcc: C compiler needed for building Python packages with C extensions
+# g++: 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 \
+    g++ \
     python3-dev \
-    && rm -rf /var/lib/apt/lists/*
-
-USER appuser
+  && rm -rf /var/lib/apt/lists/*
 
-RUN mkdir -p /home/appuser/.cache
-RUN chown -R appuser /home/appuser/.cache
+# Create a new directory for our application code
+# And set it as the working directory
+WORKDIR /app
 
-WORKDIR /home/appuser
+# Copy just the dependency files first, for more efficient layer caching
+COPY requirements.txt ./
 
-COPY requirements.txt .
-RUN python -m pip install --user --no-cache-dir -r requirements.txt
+# Install Python dependencies using pip
+# --no-cache-dir ensures we don't use the system cache
+RUN pip install --no-cache-dir -r requirements.txt
 
+# Copy all remaining pplication files into the container
+# This includes source code, configuration files, and dependency specifications
+# (Excludes files specified in .dockerignore)
 COPY . .
 
-# ensure that any dependent models are downloaded at build-time
-RUN python "$PROGRAM_MAIN" download-files
+# 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
 
-# expose healthcheck port
-EXPOSE 8081
+# 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 python "{{.ProgramMain}}" download-files
 
-# Run the application.
+# Run the application
 # The "start" command tells the worker to connect to LiveKit and begin waiting for jobs.
 CMD ["python", "{{.ProgramMain}}", "start"]

pkg/agentfs/examples/python.pip.dockerignore

@@ -1,26 +1,48 @@
-# Python artifacts
-venv/
+# Python bytecode and artifacts
 __pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.egg-info/
+dist/
+build/
 
-# Local environment & config files
-.env
-.env.local
-.DS_Store
+# Virtual environments
+.venv/
+venv/
 
-# Logs & temp files
+# Caches and test output
+.cache/
+.pytest_cache/
+.ruff_cache/
+coverage/
+
+# Logs and temp files
 *.log
 *.gz
 *.tgz
 .tmp
 .cache
 
-# Docker artifacts
-Dockerfile*
-.dockerignore
+# Environment variables
+.env
+.env.*
 
-# Git & Editor files
+# VCS, editor, OS
 .git
 .gitignore
-.idea
-.vscode
+.gitattributes
+.github/
+.idea/
+.vscode/
+.DS_Store
+
+# Project docs and misc
+README.md
+LICENSE
 
+# Project tests
+test/
+tests/
+eval/
+evals/

pkg/agentfs/examples/python.uv.Dockerfile

@@ -1,77 +1,72 @@
-# This sample Dockerfile creates a production-ready container for a LiveKit voice AI agent
+# This is an example Dockerfile that builds a minimal container for running LK Agents
+# For more information on the build process, see https://docs.livekit.io/agents/ops/deployment/builds/
 # 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
-FROM ghcr.io/astral-sh/uv:python3.11-bookworm-slim
+ARG PYTHON_VERSION=3.11
+FROM ghcr.io/astral-sh/uv:python${PYTHON_VERSION}-bookworm-slim AS base
 
 # Keeps Python from buffering stdout and stderr to avoid situations where
 # the application crashes without emitting any logs due to buffering.
 ENV PYTHONUNBUFFERED=1
 
-# Define the program entrypoint file where your agent is started.
-ARG PROGRAM_MAIN="{{.ProgramMain}}"
-
 # 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 "" \
-    --home "/home/appuser" \
+    --home "/app" \
     --shell "/sbin/nologin" \
     --uid "${UID}" \
     appuser
 
 # Install build dependencies required for Python packages with native extensions
 # gcc: C compiler needed for building Python packages with C extensions
+# g++: 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 \
+RUN apt-get update && apt-get install -y \
     gcc \
+    g++ \
     python3-dev \
-    && rm -rf /var/lib/apt/lists/*
+  && rm -rf /var/lib/apt/lists/*
+
+# Create a new directory for our application code
+# And set it as the working directory
+WORKDIR /app
 
-# Set the working directory to the user's home directory
-# This is where our application code will live
-WORKDIR /home/appuser
+# Copy just the dependency files first, for more efficient layer caching
+COPY pyproject.toml uv.lock ./
+RUN mkdir -p src
 
-# Copy all application files into the container
+# 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 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 /home/appuser
+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
 
-# Create a cache directory for the user
-# This is used by UV and Python for caching packages and bytecode
-RUN mkdir -p /home/appuser/.cache
-
-# 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
-
 # 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 "$PROGRAM_MAIN" download-files
-
-# Expose the healthcheck port
-# This allows Docker and orchestration systems to check if the container is healthy
-EXPOSE 8081
+RUN uv run "{{.ProgramMain}}" download-files
 
 # 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", "{{.ProgramMain}}", "start"]
-