Skip to content

Commit 84d8c4b

Browse files
dwayndwayn
committed
docs(agents): Distilled dockerfile docs into a readme
Simplified the documentation on the Dockerfile templates and added a README with the distilled documentation from all of the dockerfiles
1 parent 994b35e commit 84d8c4b

12 files changed

+1256
-1509
lines changed

‎pkg/agentfs/examples/README.md‎

Lines changed: 1059 additions & 0 deletions
Large diffs are not rendered by default.

‎pkg/agentfs/examples/node.bun.Dockerfile‎

Lines changed: 16 additions & 114 deletions
Original file line numberDiff line numberDiff line change
@@ -1,58 +1,41 @@
1-
# This Dockerfile creates a production-ready container for a LiveKit Node.js agent using Bun
2-
# It uses a multi-stage build to minimize the final image size
31
# syntax=docker/dockerfile:1
2+
# For detailed documentation and guides, see:
3+
# https://github.com/livekit/livekit-cli/blob/main/pkg/agentfs/examples/README.md
4+
# For more help: https://docs.livekit.io/agents/
5+
# For help with building and deployment: https://docs.livekit.io/agents/ops/deployment/cloud/build
46

5-
# === MULTI-STAGE BUILD STRUCTURE ===
6-
# Stage 1 (base): Sets up Bun runtime environment
7-
# Stage 2 (build): Installs dependencies and builds the application
8-
# Stage 3 (final): Copies only necessary files for runtime
9-
#
10-
# Benefits: Smaller final image without build tools and source files
11-
# Final image contains only: compiled JS, node_modules, and runtime dependencies
12-
13-
# Use official Bun image as base
147
ARG BUN_VERSION=1
158
FROM oven/bun:${BUN_VERSION} AS base
169

17-
# Define the program entrypoint file where your agent is started.
10+
# Define the program entrypoint file where your agent is started
1811
ARG PROGRAM_MAIN="{{.ProgramMain}}"
1912

20-
# Set the working directory where our application will live
2113
WORKDIR /app
2214

2315
# === BUILD STAGE ===
24-
# This stage is discarded after building, keeping the final image small
2516
FROM base AS build
2617

27-
# Copy package.json and lock file first for better layer caching
28-
# This allows Docker to cache the dependency installation step
18+
# Copy package files first for layer caching
2919
COPY package.json bun.lock* ./
3020

31-
# Install dependencies using bun
32-
# Bun automatically uses the lock file if it exists
33-
# Install all dependencies including dev for the build stage
21+
# Install all dependencies
3422
RUN bun install --frozen-lockfile
3523

36-
# Set production environment
3724
ENV NODE_ENV=production
3825

39-
# Copy all application files into the build container
26+
# Copy source code
4027
COPY . .
4128

42-
# Build the TypeScript application (if needed)
43-
# Bun can run TypeScript directly, but building may still be needed for bundling
29+
# Build if needed (Bun can run TypeScript directly)
4430
RUN bun run build
4531

46-
# Prune any dev dependencies that might have been needed for build
47-
# This keeps only production dependencies
32+
# Reinstall production only
4833
RUN bun install --production
4934

50-
# === FINAL PRODUCTION STAGE ===
51-
# Start from the base image without build tools
35+
# === RUNTIME STAGE ===
5236
FROM base
5337

54-
# Create a non-privileged user that the app will run under.
55-
# See https://docs.docker.com/develop/develop-images/dockerfile_best-practices/#user
38+
# Create non-privileged user
5639
ARG UID=10001
5740
RUN adduser \
5841
--disabled-password \
@@ -62,93 +45,12 @@ RUN adduser \
6245
--uid "${UID}" \
6346
appuser
6447

65-
# Copy the built application from the build stage
66-
# This includes node_modules and compiled JavaScript files
48+
# Copy built application from build stage
6749
COPY --from=build /app /app
6850

69-
# Change ownership of all app files to the non-privileged user
70-
# This ensures the application can read/write files as needed
51+
# Set ownership and switch user
7152
RUN chown -R appuser:appuser /app
72-
73-
# Switch to the non-privileged user for all subsequent operations
74-
# This improves security by not running as root
7553
USER appuser
7654

77-
# Run the application using Bun
78-
# The "start" command tells the agent to connect to LiveKit and begin waiting for jobs
79-
# Bun can run TypeScript directly, but we use the built JS for production
80-
CMD [ "bun", "run", "{{.ProgramMain}}", "start" ]
81-
82-
# === COMMON CUSTOMIZATIONS ===
83-
#
84-
# 1. Production-only dependencies:
85-
# To install only production dependencies (exclude devDependencies):
86-
# RUN bun install --frozen-lockfile --production
87-
#
88-
# 2. Direct TypeScript execution:
89-
# Bun can run TypeScript files directly without compilation:
90-
# CMD ["bun", "run", "./src/agent.ts", "start"]
91-
#
92-
# 3. Different entry point locations:
93-
# - If using src/index.ts: CMD ["bun", "run", "./src/index.ts", "start"]
94-
# - If using dist/main.js: CMD ["bun", "run", "./dist/main.js", "start"]
95-
# - For development: CMD ["bun", "run", "dev"]
96-
#
97-
# 4. Environment variables:
98-
# Set Node.js environment for production:
99-
# ENV NODE_ENV=production
100-
#
101-
# 5. Running as non-root user (recommended for security):
102-
# Add before the final CMD:
103-
# RUN adduser --disabled-password --gecos "" --uid 10001 appuser
104-
# USER appuser
105-
#
106-
# 6. Using Node.js compatibility mode:
107-
# Some packages may need Node.js APIs:
108-
# CMD ["bun", "--bun", "run", "{{.ProgramMain}}", "start"]
109-
#
110-
# === TROUBLESHOOTING BUN-SPECIFIC ISSUES ===
111-
#
112-
# 1. "bun.lock not found":
113-
# - Run `bun install` locally to generate bun.lock
114-
# - Commit bun.lock to version control for reproducible builds
115-
# - Use --frozen-lockfile for production builds
116-
#
117-
# 2. "Module not found" errors:
118-
# - Ensure all dependencies are in package.json
119-
# - Bun uses a different module resolution than Node.js
120-
# - Try using --bun flag for better compatibility
121-
# - Check that node_modules are copied correctly
122-
#
123-
# 3. Node.js API compatibility:
124-
# - Some Node.js APIs may not be fully implemented
125-
# - Use --bun flag to enable Bun's runtime
126-
# - Consider fallback to Node.js for incompatible packages
127-
#
128-
# 4. TypeScript issues:
129-
# - Bun runs TypeScript natively, no compilation needed
130-
# - However, some TypeScript features may differ
131-
# - Check tsconfig.json compatibility with Bun
132-
#
133-
# 5. Large image sizes:
134-
# - Use oven/bun:alpine for smaller base image
135-
# - Ensure .dockerignore excludes unnecessary files
136-
# - Use bun install --production for production builds
137-
#
138-
# 6. Performance differences:
139-
# - Bun is generally faster for startup and execution
140-
# - However, some optimizations may differ from Node.js
141-
# - Profile your application if performance issues arise
142-
#
143-
# 7. Native module issues:
144-
# - Bun has different native module support than Node.js
145-
# - Some Node.js native modules may not work
146-
# - Check Bun's compatibility list for your dependencies
147-
#
148-
# 8. Runtime connection issues:
149-
# - Verify the agent can reach the LiveKit server
150-
# - Check that required environment variables are set
151-
# - Ensure the healthcheck endpoint (8081) is accessible
152-
#
153-
# For more help: https://bun.sh/docs
154-
# For LiveKit agent build help: https://docs.livekit.io/agents/ops/deployment/cloud/build
55+
# Bun can run TypeScript directly
56+
CMD [ "bun", "run", "{{.ProgramMain}}", "start" ]

‎pkg/agentfs/examples/node.npm.Dockerfile‎

Lines changed: 18 additions & 116 deletions
Original file line numberDiff line numberDiff line change
@@ -1,64 +1,44 @@
1-
# This Dockerfile creates a production-ready container for a LiveKit Node.js agent using npm
2-
# It uses a multi-stage build to minimize the final image size
31
# syntax=docker/dockerfile:1
4-
5-
# === MULTI-STAGE BUILD STRUCTURE ===
6-
# Stage 1 (base): Sets up Node.js environment
7-
# Stage 2 (build): Installs dependencies and builds the application
8-
# Stage 3 (final): Copies only necessary files for runtime
9-
#
10-
# Benefits: Smaller final image without build tools and source files
11-
# Final image contains only: compiled JS, node_modules, and runtime dependencies
2+
# For detailed documentation and guides, see:
3+
# https://github.com/livekit/livekit-cli/blob/main/pkg/agentfs/examples/README.md
4+
# For more help: https://docs.livekit.io/agents/
5+
# For help with building and deployment: https://docs.livekit.io/agents/ops/deployment/cloud/build
126

137
ARG NODE_VERSION=22
148
FROM node:${NODE_VERSION}-slim AS base
159

16-
# Define the program entrypoint file where your agent is started.
10+
# Define the program entrypoint file where your agent is started
1711
ARG PROGRAM_MAIN="{{.ProgramMain}}"
1812

19-
# Set the working directory where our application will live
2013
WORKDIR /app
2114

2215
# === BUILD STAGE ===
23-
# This stage is discarded after building, keeping the final image small
2416
FROM base AS build
2517

26-
# Install CA certificates for HTTPS connections during package installation
27-
# --no-install-recommends keeps the image smaller by avoiding suggested packages
18+
# Install CA certificates for HTTPS connections
2819
RUN apt-get update -qq && apt-get install --no-install-recommends -y ca-certificates
2920

30-
# Copy package.json and package-lock.json first for better layer caching
31-
# This allows Docker to cache the dependency installation step
21+
# Copy package files first for layer caching
3222
COPY package*.json ./
3323

34-
# Install dependencies using npm ci
35-
# npm ci is faster and more reliable for production builds than npm install
36-
# It requires package-lock.json and installs exact versions
37-
# must run this without --only=production because it won't work with typescript
38-
# projects because typescript is not a production dependency, npm prune will
39-
# remove dev dependencies further down
24+
# Install all dependencies including dev dependencies for TypeScript
4025
RUN npm ci
4126

42-
# Copy all application files into the build container
27+
# Copy source code
4328
COPY . .
4429

45-
# Build the TypeScript application
46-
# This compiles TypeScript to JavaScript and prepares for production
30+
# Build TypeScript to JavaScript
4731
RUN npm run build
4832

49-
# Remove development dependencies after build
50-
# This reduces the final image size
33+
# Remove dev dependencies after build
5134
RUN npm prune --production
5235

53-
# === FINAL PRODUCTION STAGE ===
54-
# Start from the base image without build tools
36+
# === RUNTIME STAGE ===
5537
FROM base
5638

57-
# Set production environment for runtime
5839
ENV NODE_ENV=production
5940

60-
# Create a non-privileged user that the app will run under.
61-
# See https://docs.docker.com/develop/develop-images/dockerfile_best-practices/#user
41+
# Create non-privileged user
6242
ARG UID=10001
6343
RUN adduser \
6444
--disabled-password \
@@ -68,93 +48,15 @@ RUN adduser \
6848
--uid "${UID}" \
6949
appuser
7050

71-
# Copy the built application from the build stage
72-
# This includes node_modules and compiled JavaScript files
51+
# Copy built application from build stage
7352
COPY --from=build /app /app
7453

75-
# Copy SSL certificates for HTTPS connections at runtime
54+
# Copy SSL certificates for HTTPS
7655
COPY --from=build /etc/ssl/certs /etc/ssl/certs
7756

78-
# Change ownership of all app files to the non-privileged user
79-
# This ensures the application can read/write files as needed
57+
# Set ownership and switch user
8058
RUN chown -R appuser:appuser /app
81-
82-
# Switch to the non-privileged user for all subsequent operations
83-
# This improves security by not running as root
8459
USER appuser
8560

86-
# Run the application
87-
# The "start" command tells the agent to connect to LiveKit and begin waiting for jobs
88-
CMD [ "node", "{{.ProgramMain}}", "start" ]
89-
90-
# === COMMON CUSTOMIZATIONS ===
91-
#
92-
# 1. Production-only dependencies:
93-
# To install only production dependencies (exclude devDependencies):
94-
# RUN npm ci --omit=dev
95-
#
96-
# 2. Installing system dependencies for native modules:
97-
# Some Node.js packages require system libraries. Add before COPY in build stage:
98-
#
99-
# # For packages with native C++ addons:
100-
# RUN apt-get update -qq && apt-get install --no-install-recommends -y \
101-
# ca-certificates \
102-
# python3 \
103-
# make \
104-
# g++ \
105-
# && rm -rf /var/lib/apt/lists/*
106-
#
107-
# 3. Different entry point locations:
108-
# - If using src/index.js: CMD ["node", "./src/index.js", "start"]
109-
# - If using dist/main.js: CMD ["node", "./dist/main.js", "start"]
110-
# - For development: CMD ["npm", "run", "dev"]
111-
#
112-
# 4. Environment variables:
113-
# Set Node.js environment for production:
114-
# ENV NODE_ENV=production
115-
#
116-
# 5. Running as non-root user (recommended for security):
117-
# Add before the final CMD:
118-
# RUN adduser --disabled-password --gecos "" --uid 10001 appuser
119-
# USER appuser
120-
#
121-
# === TROUBLESHOOTING NPM-SPECIFIC ISSUES ===
122-
#
123-
# 1. "package-lock.json not found":
124-
# - Run `npm install` locally to generate package-lock.json
125-
# - Commit package-lock.json to version control
126-
# - npm ci requires package-lock.json for reproducible builds
127-
#
128-
# 2. "Module not found" errors:
129-
# - Ensure all dependencies are in package.json
130-
# - Check that build output is in the expected location
131-
# - Verify node_modules are copied correctly
132-
#
133-
# 3. "EACCES: permission denied" errors:
134-
# - Add a non-root user (see example above)
135-
# - Ensure files have correct permissions
136-
#
137-
# 4. Large image sizes:
138-
# - Use node:20-alpine instead of node:20-slim for smaller base
139-
# - Ensure .dockerignore excludes unnecessary files
140-
# - Consider using npm prune --production after build
141-
# - Use npm ci --omit=dev for production installs
142-
#
143-
# 5. Slow builds:
144-
# - Use Docker BuildKit: DOCKER_BUILDKIT=1 docker build
145-
# - Order COPY commands from least to most frequently changed
146-
# - Copy package.json and package-lock.json before source code for better caching
147-
# - npm ci is faster than npm install for CI/production builds
148-
#
149-
# 6. Native module compilation issues:
150-
# - Install build tools in the build stage (see customization #2)
151-
# - For node-gyp: apt-get install python3 make g++
152-
# - Consider using prebuilt binaries when available
153-
#
154-
# 7. Runtime connection issues:
155-
# - Verify the agent can reach the LiveKit server
156-
# - Check that required environment variables are set
157-
# - Ensure the healthcheck endpoint (8081) is accessible
158-
#
159-
# For more help: https://docs.livekit.io/agents/
160-
# For build options and troubleshooting: https://docs.livekit.io/agents/ops/deployment/cloud/build
61+
# Start the agent
62+
CMD [ "node", "{{.ProgramMain}}", "start" ]

0 commit comments

Comments
 (0)