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
3+ # syntax=docker/dockerfile:1
4+
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
14+ FROM oven/bun:1 AS base
15+
16+ # Define the program entrypoint file where your agent is started.
17+ ARG PROGRAM_MAIN="{{.ProgramMain}}"
18+
19+ # Set the working directory where our application will live
20+ WORKDIR /app
21+
22+ # === BUILD STAGE ===
23+ # This stage is discarded after building, keeping the final image small
24+ FROM base AS build
25+
26+ # Copy package.json and bun.lockb first for better layer caching
27+ # This allows Docker to cache the dependency installation step
28+ COPY package.json bun.lockb* ./
29+
30+ # Install dependencies using bun
31+ # Bun automatically uses the lock file if it exists
32+ RUN bun install --frozen-lockfile
33+
34+ # Copy all application files into the build container
35+ COPY . .
36+
37+ # Build the TypeScript application (if needed)
38+ # Bun can run TypeScript directly, but building may still be needed for bundling
39+ RUN bun run build
40+
41+ # === FINAL PRODUCTION STAGE ===
42+ # Start from the base image without build tools
43+ FROM base
44+
45+ # Copy the built application from the build stage
46+ # This includes node_modules and compiled JavaScript files
47+ COPY --from=build /app /app
48+
49+ # Expose the healthcheck port
50+ # This allows Docker and orchestration systems to check if the container is healthy
51+ EXPOSE 8081
52+
53+ # Run the application using Bun
54+ # The "start" command tells the agent to connect to LiveKit and begin waiting for jobs
55+ # Bun can run TypeScript directly, but we use the built JS for production
56+ CMD [ "bun" , "run" , "{{.ProgramMain}}" , "start" ]
57+
58+ # === COMMON CUSTOMIZATIONS ===
59+ #
60+ # 1. Production-only dependencies:
61+ # To install only production dependencies (exclude devDependencies):
62+ # RUN bun install --frozen-lockfile --production
63+ #
64+ # 2. Direct TypeScript execution:
65+ # Bun can run TypeScript files directly without compilation:
66+ # CMD ["bun", "run", "./src/agent.ts", "start"]
67+ #
68+ # 3. Different entry point locations:
69+ # - If using src/index.ts: CMD ["bun", "run", "./src/index.ts", "start"]
70+ # - If using dist/main.js: CMD ["bun", "run", "./dist/main.js", "start"]
71+ # - For development: CMD ["bun", "run", "dev"]
72+ #
73+ # 4. Environment variables:
74+ # Set Node.js environment for production:
75+ # ENV NODE_ENV=production
76+ #
77+ # 5. Running as non-root user (recommended for security):
78+ # Add before the final CMD:
79+ # RUN adduser --disabled-password --gecos "" --uid 10001 appuser
80+ # USER appuser
81+ #
82+ # 6. Using Node.js compatibility mode:
83+ # Some packages may need Node.js APIs:
84+ # CMD ["bun", "--bun", "run", "{{.ProgramMain}}", "start"]
85+ #
86+ # === TROUBLESHOOTING BUN-SPECIFIC ISSUES ===
87+ #
88+ # 1. "bun.lockb not found":
89+ # - Run `bun install` locally to generate bun.lockb
90+ # - This is a binary file, ensure it's committed to version control
91+ # - Use --frozen-lockfile for reproducible builds
92+ #
93+ # 2. "Module not found" errors:
94+ # - Ensure all dependencies are in package.json
95+ # - Bun uses a different module resolution than Node.js
96+ # - Try using --bun flag for better compatibility
97+ # - Check that node_modules are copied correctly
98+ #
99+ # 3. Node.js API compatibility:
100+ # - Some Node.js APIs may not be fully implemented
101+ # - Use --bun flag to enable Bun's runtime
102+ # - Consider fallback to Node.js for incompatible packages
103+ #
104+ # 4. TypeScript issues:
105+ # - Bun runs TypeScript natively, no compilation needed
106+ # - However, some TypeScript features may differ
107+ # - Check tsconfig.json compatibility with Bun
108+ #
109+ # 5. Large image sizes:
110+ # - Use oven/bun:alpine for smaller base image
111+ # - Ensure .dockerignore excludes unnecessary files
112+ # - Use bun install --production for production builds
113+ #
114+ # 6. Performance differences:
115+ # - Bun is generally faster for startup and execution
116+ # - However, some optimizations may differ from Node.js
117+ # - Profile your application if performance issues arise
118+ #
119+ # 7. Native module issues:
120+ # - Bun has different native module support than Node.js
121+ # - Some Node.js native modules may not work
122+ # - Check Bun's compatibility list for your dependencies
123+ #
124+ # 8. Runtime connection issues:
125+ # - Verify the agent can reach the LiveKit server
126+ # - Check that required environment variables are set
127+ # - Ensure the healthcheck endpoint (8081) is accessible
128+ #
129+ # 9. Binary lock file issues:
130+ # - bun.lockb is binary, which can cause Git issues
131+ # - Ensure Git LFS is not treating it as a large file
132+ # - Consider using text-based lockfile with --save-text-lockfile
133+ #
134+ # For more help: https://bun.sh/docs
0 commit comments