From 030565b18c444a1916c10c3f7011b09ed6387e5f Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Sun, 1 Mar 2026 19:22:44 -0800 Subject: [PATCH] Docker: add OCI base-image labels and document base-image metadata (#31196) * Docker: add OCI base image labels * Docs(Docker): document base image metadata context * Changelog: note Docker base annotation docs update * Changelog: add author credit for Docker base annotations * Update docker.md * Docker: add OCI source and docs labels * CI(Docker): publish OCI revision/version labels * Docs(Docker): list OCI image annotations * Changelog: expand OCI annotation coverage note * Docker: set OCI license annotation to MIT * Docs(Docker): align OCI license annotation to MIT * Docker: note docs sync path for OCI annotations * Docker: normalize OCI label block indentation --- .github/workflows/docker-release.yml | 44 ++++++++++++++++++++++++++++ CHANGELOG.md | 1 + Dockerfile | 13 ++++++++ docs/install/docker.md | 25 ++++++++++++++++ 4 files changed, 83 insertions(+) diff --git a/.github/workflows/docker-release.yml b/.github/workflows/docker-release.yml index eff0993b466..a0eb938f6f9 100644 --- a/.github/workflows/docker-release.yml +++ b/.github/workflows/docker-release.yml @@ -69,6 +69,27 @@ jobs: echo "EOF" } >> "$GITHUB_OUTPUT" + - name: Resolve OCI labels (amd64) + id: labels + shell: bash + run: | + set -euo pipefail + version="${GITHUB_SHA}" + if [[ "${GITHUB_REF}" == "refs/heads/main" ]]; then + version="main" + fi + if [[ "${GITHUB_REF}" == refs/tags/v* ]]; then + version="${GITHUB_REF#refs/tags/v}" + fi + created="$(date -u +%Y-%m-%dT%H:%M:%SZ)" + { + echo "value<> "$GITHUB_OUTPUT" + - name: Build and push amd64 image id: build uses: docker/build-push-action@v6 @@ -76,6 +97,7 @@ jobs: context: . platforms: linux/amd64 tags: ${{ steps.tags.outputs.value }} + labels: ${{ steps.labels.outputs.value }} cache-from: type=registry,ref=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}-cache:amd64 cache-to: type=registry,ref=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}-cache:amd64,mode=max provenance: false @@ -128,6 +150,27 @@ jobs: echo "EOF" } >> "$GITHUB_OUTPUT" + - name: Resolve OCI labels (arm64) + id: labels + shell: bash + run: | + set -euo pipefail + version="${GITHUB_SHA}" + if [[ "${GITHUB_REF}" == "refs/heads/main" ]]; then + version="main" + fi + if [[ "${GITHUB_REF}" == refs/tags/v* ]]; then + version="${GITHUB_REF#refs/tags/v}" + fi + created="$(date -u +%Y-%m-%dT%H:%M:%SZ)" + { + echo "value<> "$GITHUB_OUTPUT" + - name: Build and push arm64 image id: build uses: docker/build-push-action@v6 @@ -135,6 +178,7 @@ jobs: context: . platforms: linux/arm64 tags: ${{ steps.tags.outputs.value }} + labels: ${{ steps.labels.outputs.value }} cache-from: type=registry,ref=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}-cache:arm64 cache-to: type=registry,ref=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}-cache:arm64,mode=max provenance: false diff --git a/CHANGELOG.md b/CHANGELOG.md index 9e4d0c2f781..317ffa202f6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -119,6 +119,7 @@ Docs: https://docs.openclaw.ai - Matrix/Directory room IDs: preserve original room-ID casing for direct `!roomId` group lookups (without `:server`) so allowlist checks do not fail on case-sensitive IDs. Landed from contributor PR #31201 by @williamos-dev. Thanks @williamos-dev. - Discord/Inbound media fallback: preserve attachment and sticker metadata when Discord CDN fetch/save fails by keeping URL-based media entries in context, with regression coverage for save failures and mixed success/failure ordering. Landed from contributor PR #28906 by @Sid-Qin. Thanks @Sid-Qin. - Docs/Docker images: clarify the official GHCR image source and tag guidance (`main`, `latest`, ``), and document that `OPENCLAW_IMAGE` skips local image builds but still uses the repo-local compose/setup flow. (#27214, #31180) Fixes #15655. Thanks @ipl31. +- Docker/Image base annotations: add OCI labels for base image plus source/documentation/license metadata, include revision/version/created labels in Docker release builds, and document annotation keys/release context in install docs. Fixes #27945. Thanks @vincentkoc. - Agents/Model fallback: classify additional network transport errors (`ECONNREFUSED`, `ENETUNREACH`, `EHOSTUNREACH`, `ENETRESET`, `EAI_AGAIN`) as failover-worthy so fallback chains advance when primary providers are unreachable. Landed from contributor PR #19077 by @ayanesakura. Thanks @ayanesakura. - Agents/Copilot token refresh: refresh GitHub Copilot runtime API tokens after auth-expiry failures and re-run with the renewed token so long-running embedded/subagent turns do not fail on mid-session 401 expiry. Landed from contributor PR #8805 by @Arthur742Ramos. Thanks @Arthur742Ramos. - Agents/Subagents delivery params: reject unsupported `sessions_spawn` channel-delivery params (`target`, `channel`, `to`, `threadId`, `replyTo`, `transport`) with explicit input errors so delivery intent does not silently leak output to the parent conversation. (#31000) diff --git a/Dockerfile b/Dockerfile index 48d4baf6a06..3ba413c70d9 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,5 +1,18 @@ FROM node:22-bookworm@sha256:cd7bcd2e7a1e6f72052feb023c7f6b722205d3fcab7bbcbd2d1bfdab10b1e935 +# OCI base-image metadata for downstream image consumers. +# If you change these annotations, also update: +# - docs/install/docker.md ("Base image metadata" section) +# - https://docs.openclaw.ai/install/docker +LABEL org.opencontainers.image.base.name="docker.io/library/node:22-bookworm" \ + org.opencontainers.image.base.digest="sha256:cd7bcd2e7a1e6f72052feb023c7f6b722205d3fcab7bbcbd2d1bfdab10b1e935" \ + org.opencontainers.image.source="https://github.com/openclaw/openclaw" \ + org.opencontainers.image.url="https://openclaw.ai" \ + org.opencontainers.image.documentation="https://docs.openclaw.ai/install/docker" \ + org.opencontainers.image.licenses="MIT" \ + org.opencontainers.image.title="OpenClaw" \ + org.opencontainers.image.description="OpenClaw gateway and CLI runtime container image" + # Install Bun (required for build scripts) RUN curl -fsSL https://bun.sh/install | bash ENV PATH="/root/.bun/bin:${PATH}" diff --git a/docs/install/docker.md b/docs/install/docker.md index 5680681e936..8a40d041338 100644 --- a/docs/install/docker.md +++ b/docs/install/docker.md @@ -107,6 +107,31 @@ Common tags: - `` — release tag builds (for example `2026.2.26`) - `latest` — latest stable release tag +### Base image metadata + +The main Docker image currently uses: + +- `node:22-bookworm` + +The docker image now publishes OCI base-image annotations (sha256 is an example): + +- `org.opencontainers.image.base.name=docker.io/library/node:22-bookworm` +- `org.opencontainers.image.base.digest=sha256:cd7bcd2e7a1e6f72052feb023c7f6b722205d3fcab7bbcbd2d1bfdab10b1e935` +- `org.opencontainers.image.source=https://github.com/openclaw/openclaw` +- `org.opencontainers.image.url=https://openclaw.ai` +- `org.opencontainers.image.documentation=https://docs.openclaw.ai/install/docker` +- `org.opencontainers.image.licenses=MIT` +- `org.opencontainers.image.title=OpenClaw` +- `org.opencontainers.image.description=OpenClaw gateway and CLI runtime container image` +- `org.opencontainers.image.revision=` +- `org.opencontainers.image.version=` +- `org.opencontainers.image.created=` + +Reference: [OCI image annotations](https://github.com/opencontainers/image-spec/blob/main/annotations.md) + +Release context: this repository's tagged history already uses Bookworm in +`v2026.2.22` and earlier 2026 tags (for example `v2026.2.21`, `v2026.2.9`). + By default the setup script builds the image from source. To pull a pre-built image instead, set `OPENCLAW_IMAGE` before running the script: