From f200fa9f7a96c9c377bd03cb89b1ad6414ca36ef Mon Sep 17 00:00:00 2001 From: Ben Cherry Date: Fri, 18 Jul 2025 16:08:54 -0400 Subject: [PATCH] Changes --- .dockerignore | 18 +++++++++ .github/workflows/tests.yml | 16 ++++++++ .gitignore | 1 - Dockerfile | 73 +++++++++++++++++++++++++++++++++++++ README.md | 12 ++++++ 5 files changed, 119 insertions(+), 1 deletion(-) create mode 100644 .dockerignore create mode 100644 Dockerfile diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..79113e0 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,18 @@ +*.egg-info +__pycache__ +.pytest_cache +.ruff_cache +.env +.env.* +.DS_Store +.idea +.venv +.vscode +*.pyc +*.pyo +*.pyd +.git +.gitignore +README.md +LICENSE +.github diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 3120bf1..19fcb53 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -13,6 +13,22 @@ jobs: steps: - uses: actions/checkout@v4 + # As this is a starter template project, we don't want to check in the uv.lock and livekit.toml files in its template form + # However, once you have cloned this repo for your own use, LiveKit recommends you check them in and remove this check + - name: Check files not tracked in git + run: | + if git ls-files | grep -q "^uv\.lock$"; then + echo "Error: uv.lock should not be checked into git" + echo "Disable this test and commit the file once you have cloned this repo for your own use" + exit 1 + fi + if git ls-files | grep -q "^livekit\.toml$"; then + echo "Error: livekit.toml should not be checked into git" + echo "Disable this test and commit the file once you have cloned this repo for your own use" + exit 1 + fi + echo "✓ uv.lock and livekit.toml are correctly not tracked in git" + - name: Install uv uses: astral-sh/setup-uv@v1 with: diff --git a/.gitignore b/.gitignore index d9442dc..28ac1d0 100644 --- a/.gitignore +++ b/.gitignore @@ -4,7 +4,6 @@ __pycache__ .idea KMS -uv.lock .venv .vscode *.egg-info diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..da69aab --- /dev/null +++ b/Dockerfile @@ -0,0 +1,73 @@ +# This sample Dockerfile creates a production-ready container for a LiveKit voice AI agent +# 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 + +# 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 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" \ + --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 +# 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/* + +# Set the working directory to the user's home directory +# This is where our application code will live +WORKDIR /home/appuser + +# Copy all application 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 + +# 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 src/agent.py download-files + +# Expose the healthcheck port +# This allows Docker and orchestration systems to check if the container is healthy +EXPOSE 8081 + +# 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"] diff --git a/README.md b/README.md index 3c912ca..730c3fa 100644 --- a/README.md +++ b/README.md @@ -84,6 +84,18 @@ This project includes a complete suite of evals, based on the LiveKit Agents [te uv run pytest evals ``` +## Using this template repo for your own project + +Once you've started your own project based on this repo, you should: + +1. **Check in your `uv.lock`**: This file is currently untracked for the template, but you should commit it to your repository for reproducible builds and proper configuration management. (The same applies to `livekit.toml`, if you run your agents in LiveKit Cloud) + +2. **Remove the git tracking test**: Delete the "Check files not tracked in git" step from `.github/workflows/tests.yml` since you'll now want this file to be tracked. These are just there for development purposes in the template repo itself. + +## Deploying to production + +This project is production-ready and includes a working `Dockerfile`. To deploy it to LiveKit Cloud or another environment, see the [deploying to production](https://docs.livekit.io/agents/ops/deployment/) guide. + ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. \ No newline at end of file