Claude Code: Optimize Dockerfile for production deployment

Optimizations:
- Use node:22-bookworm-slim for smaller base image
- Separate Python package installation layer for caching
- Add proper health check endpoint configuration
- Add build arguments for configurable versions
- Clean apt cache to reduce image size
- Add metadata labels for better image tracking
- Document each optimization decision with comments
- Add PYTHONUNBUFFERED and PYTHONDONTWRITEBYTECODE for stability
- Improve directory structure creation in single layer
- Proper signal handling documentation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Dockerfile

@@ -1,41 +1,97 @@
-# OpenClaw on Hugging Face Spaces — Pre-built image (v4.1)
-# Uses official pre-built image to avoid 30+ minute builds on cpu-basic
+# OpenClaw on Hugging Face Spaces — Optimized Production Build (v4.2)
+# Optimizations: multi-stage build, layer caching, health checks, signal handling
 
 # ── Stage 1: Pull pre-built OpenClaw ─────────────────────────────────────────
 FROM ghcr.io/openclaw/openclaw:latest AS openclaw-prebuilt
 
-# ── Stage 2: Runtime ─────────────────────────────────────────────────────────
-FROM node:22-bookworm
+# ── Stage 2: Runtime with Node.js + Python ───────────────────────────────────
+# Using node:22-bookworm-slim for smaller base image size
+FROM node:22-bookworm-slim
+
+# Metadata for healthcheck and labeling
+LABEL maintainer="HuggingClaw"
+LABEL description="OpenClaw Cain - HuggingFace Space with Gradio Dashboard"
+LABEL version="4.2.0"
+
 SHELL ["/bin/bash", "-c"]
 
+# ── Build arguments for configurable versions ─────────────────────────────────
+ARG PYTHON_VERSION=python3.10
+ARG NODE_ENV=production
+
 # ── System dependencies (root) ───────────────────────────────────────────────
-RUN echo "[build] Installing system deps..." && START=$(date +%s) \
+# Optimization: Install Python and system deps in minimal layers for caching
+RUN echo "[build] Installing system dependencies..." && START=$(date +%s) \
   && apt-get update \
-  && apt-get install -y --no-install-recommends git ca-certificates curl python3 python3-pip \
+  # Minimal install: git for cloning, ca-certificates for HTTPS, curl for health checks
+  && apt-get install -y --no-install-recommends \
+    git \
+    ca-certificates \
+    curl \
+    ${PYTHON_VERSION} \
+    ${PYTHON_VERSION}-pip \
+    ${PYTHON_VERSION}-venv \
+  # Clean apt cache to reduce image size
   && rm -rf /var/lib/apt/lists/* \
-  && pip3 install --no-cache-dir --break-system-packages huggingface_hub requests gradio psutil fastapi uvicorn[standard] \
-  && corepack enable \
-  && mkdir -p /app/openclaw \
-  && chown -R node:node /app \
-  && mkdir -p /home/node/.openclaw/workspace /home/node/.openclaw/credentials \
-  && chown -R node:node /home/node \
+  && apt-get clean \
   && echo "[build] System deps: $(($(date +%s) - START))s"
 
+# ── Python dependencies (separate layer for Docker caching) ────────────────
+# Optimization: Copy requirements first for better layer caching when only code changes
+COPY requirements.txt /tmp/requirements.txt
+
+RUN echo "[build] Installing Python packages..." && START=$(date +%s) \
+  # Use --no-cache-dir to avoid pip cache (saves space)
+  # Use --break-system-packages for Debian Python (required in bookworm-slim)
+  && pip3 install --no-cache-dir --break-system-packages \
+    -r /tmp/requirements.txt \
+  # Remove temporary requirements file
+  && rm /tmp/requirements.txt \
+  && echo "[build] Python packages: $(($(date +%s) - START))s"
+
+# ── Node.js package management ───────────────────────────────────────────────
+# Enable corepack for npm/yarn/pnpm management
+RUN corepack enable
+
+# ── Directory setup with proper permissions ───────────────────────────────────
+# Optimization: Create all directories in a single layer with correct ownership
+RUN echo "[build] Setting up directories..." \
+  && mkdir -p \
+    /app/openclaw \
+    /home/node/.openclaw/workspace \
+    /home/node/.openclaw/credentials \
+    /home/node/.local/bin \
+  && chown -R node:node /app /home/node \
+  # Add node user to sudoers for npm global installs if needed (optional)
+  # Set proper umask for security
+  && echo "[build] Directories created"
+
 # ── Claude Code CLI (for coding agent extension — uses z.ai/Zhipu GLM) ──────
+# Install in separate layer for caching
 RUN echo "[build] Installing Claude Code CLI..." && START=$(date +%s) \
   && npm install -g @anthropic-ai/claude-code \
   && echo "[build] Claude Code CLI: $(($(date +%s) - START))s"
 
 # ── Copy pre-built OpenClaw (skips clone + install + build entirely) ─────────
+# Use chown to set correct ownership
 COPY --from=openclaw-prebuilt --chown=node:node /app /app/openclaw
 
+# ── Version extraction from OpenClaw ──────────────────────────────────────────
+RUN echo "[build] Extracting OpenClaw version..." \
+  && node -e "try{console.log(require('/app/openclaw/package.json').version)}catch(e){console.log('unknown')}" \
+    > /app/openclaw/.version \
+  && echo "[build] OpenClaw version: $(cat /app/openclaw/.version)"
+
+# ── Switch to non-root user for security ──────────────────────────────────────
 USER node
 ENV HOME=/home/node
 WORKDIR /app
 
 # ── A2A Gateway Extension ───────────────────────────────────────────────────
+# Install extension as non-root user
 RUN echo "[build] Installing A2A gateway..." && START=$(date +%s) \
-  && git clone --depth 1 https://github.com/win4r/openclaw-a2a-gateway.git /app/openclaw/extensions/a2a-gateway \
+  && git clone --depth 1 https://github.com/win4r/openclaw-a2a-gateway.git \
+    /app/openclaw/extensions/a2a-gateway \
   && cd /app/openclaw/extensions/a2a-gateway \
   && npm install --production \
   && echo "[build] A2A gateway: $(($(date +%s) - START))s"
@@ -44,26 +100,67 @@ RUN echo "[build] Installing A2A gateway..." && START=$(date +%s) \
 COPY --chown=node:node extensions/coding-agent /app/openclaw/extensions/coding-agent
 
 # ── Prepare runtime dirs ────────────────────────────────────────────────────
-RUN mkdir -p /app/openclaw/empty-bundled-plugins \
-  && node -e "try{console.log(require('/app/openclaw/package.json').version)}catch(e){console.log('unknown')}" > /app/openclaw/.version \
-  && echo "[build] OpenClaw version: $(cat /app/openclaw/.version)"
+RUN mkdir -p /app/openclaw/empty-bundled-plugins
 
-# ── Scripts + Config + Frontend ──────────────────────────────────────────────
+# ── Scripts + Config + Frontend (copy in specific order for layer caching) ──
+# Copy scripts first (least frequently changed)
 COPY --chown=node:node scripts /home/node/scripts
-COPY --chown=node:node frontend /home/node/frontend
+RUN chmod +x /home/node/scripts/entrypoint.sh /home/node/scripts/sync_hf.py
+
+# Copy workspace templates
 COPY --chown=node:node workspace-templates /home/node/workspace-templates
+
+# Copy openclaw.json config
 COPY --chown=node:node openclaw.json /home/node/scripts/openclaw.json.default
+
+# Copy Python apps
 COPY --chown=node:node gradio_dashboard.py /home/node/gradio_dashboard.py
 COPY --chown=node:node app.py /home/node/app.py
-RUN chmod +x /home/node/scripts/entrypoint.sh /home/node/scripts/sync_hf.py \
-  && VERSION_TS=$(date +%s) \
-  && sed "s/{{VERSION_TIMESTAMP}}/${VERSION_TS}/g" /home/node/frontend/electron-standalone.html > /home/node/frontend/index.html \
+
+# Copy frontend last (most frequently changed)
+COPY --chown=node:node frontend /home/node/frontend
+
+# ── Frontend index.html with timestamp cache busting ─────────────────────────
+RUN VERSION_TS=$(date +%s) \
+  && sed "s/{{VERSION_TIMESTAMP}}/${VERSION_TS}/g" \
+    /home/node/frontend/electron-standalone.html \
+    > /home/node/frontend/index.html \
   && echo "[build] Frontend index.html generated (timestamp=${VERSION_TS})"
 
+# ── Environment variables for production ─────────────────────────────────────
+# Default values for HuggingFace Spaces compatibility
 ENV NODE_ENV=production
 ENV OPENCLAW_BUNDLED_PLUGINS_DIR=/app/openclaw/empty-bundled-plugins
 ENV OPENCLAW_PREFER_PNPM=1
 ENV PATH="/home/node/.local/bin:$PATH"
+
+# Gradio/FastAPI defaults (can be overridden by HuggingFace Spaces)
+ENV GRADIO_SERVER_NAME=0.0.0.0
+ENV PORT=7860
+ENV CAIN_API_URL="http://127.0.0.1:7860"
+
+# Python settings for stability
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONDONTWRITEBYTECODE=1
+
+# Working directory for the application
 WORKDIR /home/node
 
+# ── Health check configuration ───────────────────────────────────────────────
+# Health check endpoint: /health on FastAPI app
+# Interval: 30s, Timeout: 10s, Start period: 40s (give app time to boot)
+# Retries: 3 before marking container as unhealthy
+HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
+  CMD curl -f http://localhost:${PORT}/health || exit 1
+
+# ── Signal handling for graceful shutdown ─────────────────────────────────────
+# The entrypoint.sh script handles SIGTERM/SIGINT for graceful shutdown
+# Docker will send SIGTERM, then SIGKILL after 10 seconds if not stopped
+
+# Expose the default port (HuggingFace Spaces uses 7860)
+EXPOSE 7860
+
+# ── Entrypoint ───────────────────────────────────────────────────────────────
+# Use shell form to allow signal propagation to child processes
+# entrypoint.sh will exec the Python app which handles signals properly
 CMD ["/home/node/scripts/entrypoint.sh"]