Merge pull request #3 from livekit-examples/bcherry/deploy

Add deployment instructions and working Dockerfile
2025-07-18 19:53:10 -04:00
parent a66907e20e 642566f618
commit 279d1f14c2
6 changed files with 150 additions and 6 deletions
@@ -0,0 +1,19 @@
+*.egg-info
+__pycache__
+.pytest_cache
+.ruff_cache
+.env
+.env.*
+.DS_Store
+.idea
+.venv
+.vscode
+*.pyc
+*.pyo
+*.pyd
+.git
+.gitignore
+README.md
+LICENSE
+.github 
+tests/
@@ -0,0 +1,31 @@
+# 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 delete this github workflow entirely
+    
+name: Template Check
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  check-template-files:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Check template 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" 
@@ -4,7 +4,6 @@
 __pycache__
 .idea
 KMS
-uv.lock
 .venv
 .vscode
 *.egg-info
@@ -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"]
@@ -68,22 +68,44 @@ In production, use the `start` command:
 uv run python src/agent.py start
 ```

-## Web and mobile frontends
+## Frontend & Telephony

-To use a prebuilt frontend or build your own, see the [agents frontend guide](https://docs.livekit.io/agents/start/frontend/).
+Get started quickly with our pre-built frontend starter apps, or add telephony support:

-## Telephony
+| Platform | Link | Description |
+|----------|----------|-------------|
+| **Web** | [`livekit-examples/agent-starter-react`](https://github.com/livekit-examples/agent-starter-react) | Web voice AI assistant with React & Next.js |
+| **iOS/macOS** | [`livekit-examples/agent-starter-swift`](https://github.com/livekit-examples/agent-starter-swift) | Native iOS, macOS, and visionOS voice AI assistant |
+| **Flutter** | [`livekit-examples/agent-starter-flutter`](https://github.com/livekit-examples/agent-starter-flutter) | Cross-platform voice AI assistant app |
+| **React Native** | [`livekit-examples/voice-assistant-react-native`](https://github.com/livekit-examples/voice-assistant-react-native) | Native mobile app with React Native & Expo |
+| **Android** | [`livekit-examples/agent-starter-android`](https://github.com/livekit-examples/agent-starter-android) | Native Android app with Kotlin & Jetpack Compose |
+| **Web Embed** | [`livekit-examples/agent-starter-embed`](https://github.com/livekit-examples/agent-starter-embed) | Voice AI widget for any website |
+| **Telephony** | [📚 Documentation](https://docs.livekit.io/agents/start/telephony/) | Add inbound or outbound calling to your agent |

-To add a phone number, see the [agents telephony guide](https://docs.livekit.io/agents/start/telephony/).
+For advanced customization, see the [complete frontend guide](https://docs.livekit.io/agents/start/frontend/).

 ## Tests and evals

 This project includes a complete suite of evals, based on the LiveKit Agents [testing & evaluation framework](https://docs.livekit.io/agents/build/testing/). To run them, use `pytest`.

 ```console
-uv run pytest evals
+uv run pytest
 ```

+## 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.
+
+3. **Add your own repository secrets**: You must [add secrets](https://docs.github.com/en/actions/how-tos/writing-workflows/choosing-what-your-workflow-does/using-secrets-in-github-actions) for `OPENAI_API_KEY` or your other LLM provider so that the tests can run in CI.
+
+## 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.