Principle:Openclaw Openclaw Docker Image Build
| Knowledge Sources | |
|---|---|
| Domains | Deployment, Docker |
| Last Updated | 2026-02-06 12:00 GMT |
Overview
Docker image build is the concept of containerizing an application by creating Docker images with build-time dependencies separated from runtime to minimize image size and improve security.
Description
When deploying a TypeScript/Node.js application such as OpenClaw, the build process requires a substantial set of tools: pnpm for package management, Bun for script execution, and Node.js for compilation. The resulting runtime, however, only needs Node.js and the compiled output. Containerization encapsulates these concerns into a reproducible, portable artifact.
The OpenClaw Docker build starts from node:22-bookworm, installs Bun and enables corepack, then copies dependency manifests first to leverage Docker layer caching. A full pnpm install --frozen-lockfile ensures deterministic installs. The application source is then copied and built with pnpm build and pnpm ui:build. An optional OPENCLAW_DOCKER_APT_PACKAGES build argument allows injecting extra system packages for specialized deployments.
Security hardening is applied at the image level: the final image switches to the non-root node user (uid 1000) to reduce the attack surface. The default CMD starts the gateway server binding to loopback for security, with documented overrides for container platforms that require external health checks.
Usage
Apply this concept when deploying OpenClaw as a Docker container, whether locally via docker-setup.sh, on a cloud platform such as Fly.io or Render, or in any orchestration system (Kubernetes, Docker Compose). The Dockerfile and docker-setup.sh script together automate building the image and bootstrapping the gateway.
Theoretical Basis
The pattern follows a single-stage build with layer caching optimization:
- Dependency layer: Copy only
package.json,pnpm-lock.yaml,pnpm-workspace.yaml,.npmrc, workspace sub-package manifests, patches, and scripts. Runpnpm install --frozen-lockfile. This layer is cached as long as dependencies do not change. - Build layer: Copy all source code, run
pnpm buildandpnpm ui:build. This layer changes when source code changes but does not re-download dependencies. - Runtime configuration: Set
NODE_ENV=production, chown files to thenodeuser, switch to non-root, and define the defaultCMD.
The docker-setup.sh script orchestrates the full flow: it validates prerequisites (Docker, Docker Compose), generates a gateway token, writes environment variables to a .env file, builds the image, runs interactive onboarding, and starts the gateway service via Docker Compose.
The approach prioritizes reproducibility (frozen lockfile), security (non-root user, loopback bind), and operational flexibility (build-arg for extra packages, environment variable overrides for ports, bind mode, and authentication).