1+ # This Dockerfile creates a production-ready container for a LiveKit Node.js agent using Yarn Berry (v2+)
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 Node.js environment with Yarn Berry
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 (or PnP), and runtime dependencies
12+
13+ FROM node:20-slim AS base
14+
15+ # Define the program entrypoint file where your agent is started.
16+ ARG PROGRAM_MAIN="{{.ProgramMain}}"
17+
18+ # Set the working directory where our application will live
19+ WORKDIR /app
20+
21+ # Enable Corepack to use Yarn Berry
22+ # Corepack is Node.js's official package manager manager
23+ RUN corepack enable
24+
25+ # === BUILD STAGE ===
26+ # This stage is discarded after building, keeping the final image small
27+ FROM base AS build
28+
29+ # Install CA certificates for HTTPS connections during package installation
30+ # --no-install-recommends keeps the image smaller by avoiding suggested packages
31+ RUN apt-get update -qq && apt-get install --no-install-recommends -y ca-certificates
32+
33+ # Copy Yarn Berry configuration files first
34+ COPY .yarnrc.yml ./
35+ COPY .yarn ./.yarn
36+
37+ # Copy package.json and yarn.lock for better layer caching
38+ COPY package.json yarn.lock ./
39+
40+ # Install dependencies using Yarn Berry
41+ # --immutable ensures exact versions from yarn.lock are used
42+ # --immutable-cache ensures the cache is not modified
43+ RUN yarn install --immutable
44+
45+ # Copy all application files into the build container
46+ COPY . .
47+
48+ # Build the TypeScript application
49+ # This compiles TypeScript to JavaScript and prepares for production
50+ RUN yarn run build
51+
52+ # === FINAL PRODUCTION STAGE ===
53+ # Start from the base image without build tools
54+ FROM base
55+
56+ # Copy the built application from the build stage
57+ # This includes dependencies and compiled JavaScript files
58+ COPY --from=build /app /app
59+
60+ # Copy SSL certificates for HTTPS connections at runtime
61+ COPY --from=build /etc/ssl/certs /etc/ssl/certs
62+
63+ # Expose the healthcheck port
64+ # This allows Docker and orchestration systems to check if the container is healthy
65+ EXPOSE 8081
66+
67+ # Run the application
68+ # The "start" command tells the agent to connect to LiveKit and begin waiting for jobs
69+ CMD [ "node" , "{{.ProgramMain}}" , "start" ]
70+
71+ # === COMMON CUSTOMIZATIONS ===
72+ #
73+ # 1. Zero-Install (PnP - Plug'n'Play) mode:
74+ # If using Yarn Berry's PnP mode, ensure .pnp.cjs is copied:
75+ # COPY --from=build /app/.pnp.* ./
76+ # And update CMD to use yarn node:
77+ # CMD ["yarn", "node", "{{.ProgramMain}}", "start"]
78+ #
79+ # 2. Installing system dependencies for native modules:
80+ # Some Node.js packages require system libraries. Add before COPY in build stage:
81+ #
82+ # # For packages with native C++ addons:
83+ # RUN apt-get update -qq && apt-get install --no-install-recommends -y \
84+ # ca-certificates \
85+ # python3 \
86+ # make \
87+ # g++ \
88+ # && rm -rf /var/lib/apt/lists/*
89+ #
90+ # 3. Different entry point locations:
91+ # - If using src/index.js: CMD ["node", "./src/index.js", "start"]
92+ # - If using dist/main.js: CMD ["node", "./dist/main.js", "start"]
93+ # - For development: CMD ["yarn", "run", "dev"]
94+ #
95+ # 4. Environment variables:
96+ # Set Node.js environment for production:
97+ # ENV NODE_ENV=production
98+ #
99+ # 5. Running as non-root user (recommended for security):
100+ # Add before the final CMD:
101+ # RUN adduser --disabled-password --gecos "" --uid 10001 appuser
102+ # USER appuser
103+ #
104+ # === TROUBLESHOOTING YARN BERRY-SPECIFIC ISSUES ===
105+ #
106+ # 1. "yarn.lock not found":
107+ # - Run `yarn install` locally to generate yarn.lock
108+ # - Commit yarn.lock to version control
109+ # - --immutable requires lock file for reproducible builds
110+ #
111+ # 2. ".yarnrc.yml not found":
112+ # - Ensure .yarnrc.yml is committed to version control
113+ # - This file contains Yarn Berry configuration
114+ # - Run `yarn set version berry` locally to migrate from Yarn Classic
115+ #
116+ # 3. PnP (Plug'n'Play) issues:
117+ # - If using PnP, ensure .pnp.cjs and .pnp.loader.mjs are copied
118+ # - Use `yarn node` instead of `node` to run with PnP
119+ # - Some packages may need to be unplugged: yarn unplug <package>
120+ #
121+ # 4. "Module not found" errors:
122+ # - Check if using PnP or node_modules (nodeLinker setting)
123+ # - For PnP: ensure .pnp.* files are copied
124+ # - For node_modules: ensure they're copied correctly
125+ # - Check for hoisting issues with nmMode setting
126+ #
127+ # 5. Zero-Install not working:
128+ # - Ensure .yarn/cache is committed (for Zero-Install)
129+ # - Or add .yarn/cache to .gitignore (for traditional install)
130+ # - Check compressionLevel setting in .yarnrc.yml
131+ #
132+ # 6. Native module compilation issues:
133+ # - Install build tools in the build stage (see customization #2)
134+ # - For node-gyp: apt-get install python3 make g++
135+ # - Consider supportedArchitectures in .yarnrc.yml
136+ #
137+ # 7. Large image sizes:
138+ # - Use node:20-alpine instead of node:20-slim for smaller base
139+ # - If using Zero-Install, consider excluding .yarn/cache from Docker
140+ # - Use nmMode: hardlinks-local for smaller node_modules
141+ #
142+ # 8. Workspace issues:
143+ # - Ensure all workspace packages are included
144+ # - Use `yarn workspaces focus` for single workspace deployment
145+ # - Check nmHoistingLimits setting for workspace hoisting
146+ #
147+ # 9. Plugin issues:
148+ # - Ensure .yarn/plugins directory is copied if using plugins
149+ # - Plugins must be compatible with production environment
150+ # - Consider disabling unnecessary plugins for production
151+ #
152+ # For more help: https://yarnpkg.com/migration/guide
0 commit comments