site iconKoei's Digital Garden

Archive

Builds and Dockerfiles

4 min read

Builds and Dockerfiles

参照元: LiveKit Agents Documentation ロードマップ: 学習ロードマップ

What（何についてか）

LiveKit Cloud上でAgentをコンテナ化するためのビルドプロセスとDockerfileの書き方。CLIが自動生成するテンプレートの設計思想と、カスタマイズ時のルールを扱う。

Why（なぜ必要か）

AgentをCloudにデプロイするにはコンテナイメージが必要。ビルドプロセスとDockerfileのベストプラクティスを理解することで、ビルド失敗、イメージ肥大化、コールドスタート遅延等の問題を回避できる。

How（どう動くか）

ビルドプロセス

lk agent create または lk agent deploy 実行時に以下の流れでビルドされる。

  1. Gather files — カレントディレクトリ（または指定パス）からビルドコンテキストを準備
  2. Exclusions — .env.*、.dockerignore、.gitignore にマッチするファイルは除外
  3. Upload — ビルドコンテキストをCloud build serviceにアップロード
  4. Build — Dockerfileからコンテナイメージをビルド。ログはCLIにストリーミング

制約

  • Build timeout: 最大10分。超えるとビルド失敗
  • Build context size: 最大1GB。超えるとエラー。主な原因はモデルweights、.venv/、node_modules/

Dockerfileの必須要件

  • Base image: glibcベース（Debian/Ubuntu）。Alpine（musl）は非対応。-slim 変体を推奨
  • Unprivileged user: rootで実行してはいけない
  • WORKDIR: 明示的に設定（例: /app）
  • ENTRYPOINT/CMD: start コマンドでAgentを直接起動。バックグラウンド実行やラッパースクリプトは禁止

ベストプラクティス

  • キャッシュ最適化: lockfile → 依存インストール → ソースコピーの順でレイヤーキャッシュを活用。ソース変更時に依存再インストールを避ける
  • バージョン固定: lockfileを使って再現性を保証（uv sync --locked / pnpm install --frozen-lockfile）
  • レイヤーを小さく: aptキャッシュ等はインストール直後に削除
  • Secret禁止: .env* をイメージに含めない。LiveKit CloudのSecrets Managementでランタイム注入
  • LiveKit環境変数禁止: LIVEKIT_URL / LIVEKIT_API_KEY / LIVEKIT_API_SECRET はCloudが自動注入
  • モデル・アセットはビルド時にダウンロード: download-files を使ってコールドスタートを高速化

テンプレートの設計思想（Python/uv版）

multi-stage buildの2段構成が採用されている。

graph TD
    A["base stage<br/>uv + Python + Debian Slim"] --> B["build stage<br/>gcc/g++/python3-dev + 依存インストール + download-files"]
    A --> C["production stage<br/>base のみ（コンパイラなし）"]
    B -->|"COPY --from=build"| C
    C -->|"appuser で実行"| D["CMD: uv run agent.py start"]

base stage で共通基盤（uv + Python + Debian Slim）を定義。

build stage はbaseを継承し、コンパイラ（gcc/g++/python3-dev）をインストールしてネイティブ拡張をビルド。依存ファイル（pyproject.toml + uv.lock）だけ先にコピーして uv sync --locked でインストール。その後ソースコードをコピーし、download-files でモデル等を取得。このステージのポイントは キャッシュ最適化。ソース変更時に依存レイヤーがキャッシュされる。

production stage はbaseから直接継承（buildではない）。つまりコンパイラが含まれない。build stageの成果物を COPY --from=build --chown=appuser:appuser で1レイヤーでコピー。appuser（UID 10001、シェルログイン不可）で実行。

Python Tips

  • uv推奨。base image: ghcr.io/astral-sh/uv:python3.13-bookworm-slim
  • pipの場合: python:3.11-slim
  • uv sync --locked でlockfile固定インストール

Node.js Tips

  • pnpm推奨。base image: node:22-slim
  • pnpm install --frozen-lockfile で固定
  • build / download-files / start スクリプトが package.json に必要

Key Concepts

用語説明
Multi-stage buildbuild段階とproduction段階を分け、本番イメージからビルドツールを排除
download-filesビルド時にモデル等のアセットを取得するコマンド。コールドスタート高速化
PYTHONUNBUFFERED=1コンテナ環境でPythonのログバッファリングを無効化。必須設定
--chown 付きCOPYコピーと所有権変更を1レイヤーで実行。レイヤー数削減
.dockerignoreビルドコンテキストから除外するファイル。.venv/、node_modules/ 等を指定

一言まとめ

LiveKit Cloudのビルドは最大10分・1GB制限。Dockerfileはglibcベース・非特権ユーザー・multi-stage buildが必須。公式テンプレート（Python/uv, Node.js/pnpm）は2段ビルドで本番イメージを軽量化し、download-files でコールドスタートを高速化する設計。

Graph View

Backlinks