You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maka.apache.org by as...@apache.org on 2026/09/15 15:24:26 UTC
(maka) branch main updated: feat(cli): add a local container build (#5025)
This is an automated email from the ASF dual-hosted git repository.
Astro-Han pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/maka.git
The following commit(s) were added to refs/heads/main by this push:
new ec59d42f60 feat(cli): add a local container build (#5025)
ec59d42f60 is described below
commit ec59d42f6021a4b40e18f10dad184a1821e6f0c4
Author: hbw00111 <22...@qq.com>
AuthorDate: Tue Sep 15 23:24:20 2026 +0800
feat(cli): add a local container build (#5025)
Provide a local glibc-based CLI container built from an exact published
maka-agent npm version. The digest-pinned Node 24 base installs the
registry tarball only after a SHA-512 integrity check, runs install
scripts as the non-root node user, and retains the install lockfile.
Documentation covers local builds only; official image publication
remains a separate distribution decision on #4969.
Refs #4969
Generated-by: OpenAI Codex
---
packages/cli/README.md | 6 +++
packages/cli/README.zh-CN.md | 5 +++
packages/cli/container/Dockerfile | 67 ++++++++++++++++++++++++++++++++
packages/cli/container/README.md | 80 +++++++++++++++++++++++++++++++++++++++
4 files changed, 158 insertions(+)
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 63ea420e85..8cdcc5bcba 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -80,6 +80,12 @@ The public command is `maka`. For a one-off invocation, use
`runtime-host service install` uses the persistent global installation above; `runtime-host setup`
creates its own managed copy from the exact package invoked by `npx`.
+## Container
+
+To build and run a local glibc-based CLI image from an exact published npm version
+with persistent configuration, see the
+[container guide](https://github.com/apache/maka/blob/main/packages/cli/container/README.md).
+
## First run
Start Maka from the project directory the agent should work in:
diff --git a/packages/cli/README.zh-CN.md b/packages/cli/README.zh-CN.md
index 8bac13df85..ede00ece8b 100644
--- a/packages/cli/README.zh-CN.md
+++ b/packages/cli/README.zh-CN.md
@@ -74,6 +74,11 @@ npm 上有两条 dist-tag，且二者不可互换：
无关的 `maka` 包不是本项目。`runtime-host service install` 使用上面的持久全局安装；
`runtime-host setup` 会从 `npx` 调用的精确 package 创建自己的托管副本。
+## 容器
+
+从精确的已发布 npm 版本构建和运行本地 glibc CLI 镜像，并持久化配置，见
+[容器指南](https://github.com/apache/maka/blob/main/packages/cli/container/README.md)。
+
## 第一次运行
进入希望 Agent 工作的项目目录，然后启动 Maka：
diff --git a/packages/cli/container/Dockerfile b/packages/cli/container/Dockerfile
new file mode 100644
index 0000000000..3636875dc2
--- /dev/null
+++ b/packages/cli/container/Dockerfile
@@ -0,0 +1,67 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+FROM node:24-bookworm-slim@sha256:2fe369e969550cde8e867afc3fe370b260140cab4a23d467074295b42163d553 AS base
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends ca-certificates git openssh-client python3 ripgrep tini \
+ && rm -rf /var/lib/apt/lists/*
+
+FROM base AS install
+ARG MAKA_VERSION
+RUN node -e 'if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(process.argv[1] || "")) throw new Error("MAKA_VERSION must be an exact npm version")' "$MAKA_VERSION"
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends make g++ \
+ && mkdir -p /opt/maka \
+ && chown node:node /opt/maka
+USER node
+WORKDIR /opt/maka
+# Verify the complete tarball, including bundled private @maka packages that
+# cannot be checked individually with npm audit signatures.
+RUN npm view "maka-agent@$MAKA_VERSION" dist --json --registry=https://registry.npmjs.org/ > registry-dist.json \
+ && npm pack "maka-agent@$MAKA_VERSION" --ignore-scripts --json --registry=https://registry.npmjs.org/ > packed.json
+RUN node --input-type=module <<'NODE'
+import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+import { readFileSync, renameSync } from 'node:fs';
+const { integrity } = JSON.parse(readFileSync('registry-dist.json', 'utf8'));
+const [{ filename }] = JSON.parse(readFileSync('packed.json', 'utf8'));
+const actual = `sha512-${createHash('sha512').update(readFileSync(filename)).digest('base64')}`;
+assert.equal(actual, integrity, 'maka-agent tarball must match the registry SHA-512 integrity');
+renameSync(filename, 'maka-agent.tgz');
+NODE
+# Native dependencies such as node-pty need install scripts. Run them as node,
+# only after the package bytes have been checked, and retain the install lockfile.
+RUN printf '{"private":true}\n' > package.json \
+ && npm install --save-exact --no-audit --no-fund --registry=https://registry.npmjs.org/ ./maka-agent.tgz \
+ && test "$(node -p 'require("./node_modules/maka-agent/package.json").version')" = "$MAKA_VERSION" \
+ && rm maka-agent.tgz packed.json registry-dist.json
+
+FROM base
+ARG MAKA_VERSION
+LABEL org.opencontainers.image.title="Apache Maka (Incubating) CLI" \
+ org.opencontainers.image.description="Developer convenience build; not an Apache Software Foundation release" \
+ org.opencontainers.image.source="https://github.com/apache/maka" \
+ org.opencontainers.image.licenses="Apache-2.0" \
+ org.opencontainers.image.version="$MAKA_VERSION"
+COPY --from=install /opt/maka /opt/maka
+RUN ln -s /opt/maka/node_modules/maka-agent/dist/cli.js /usr/local/bin/maka \
+ && mkdir -p /workspace /home/node/.config/Maka \
+ && chown -R node:node /workspace /home/node/.config
+USER node
+WORKDIR /workspace
+ENTRYPOINT ["/usr/bin/tini", "--", "maka"]
+CMD []
diff --git a/packages/cli/container/README.md b/packages/cli/container/README.md
new file mode 100644
index 0000000000..7f03c2ae45
--- /dev/null
+++ b/packages/cli/container/README.md
@@ -0,0 +1,80 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+# Maka CLI container
+
+This image packages an **exact, already-published** `maka-agent` npm version on
+Debian Bookworm with Node.js 24 and glibc. It is a developer convenience build,
+not an Apache Software Foundation release. Apache Maka is undergoing incubation;
+see [DISCLAIMER-WIP](../../../DISCLAIMER-WIP).
+
+The Dockerfile installs the selected version from the public npm registry; it
+does not build the checked-out source. This guide covers local builds only.
+
+## Build and run locally
+
+From the repository root, resolve the current npm Nightly once and build it:
+
+```sh
+MAKA_VERSION=$(npm view maka-agent@nightly version --registry=https://registry.npmjs.org/)
+docker build --build-arg "MAKA_VERSION=$MAKA_VERSION" \
+ --tag maka-cli:local packages/cli/container
+docker run --rm maka-cli:local --version
+docker run --rm maka-cli:local --help
+```
+
+The version argument is required. Floating tags such as `latest` and `nightly`
+are rejected by the Dockerfile so a build cannot silently select the early alpha
+on npm's `latest` channel. The downloaded tarball, including its bundled private
+packages, is checked against the public registry's SHA-512 integrity before
+installation. This verifies package bytes, not the publisher's provenance identity.
+Installation runs as the non-root `node` user and keeps a lockfile in `/opt/maka`.
+Native dependencies need install scripts, so they are enabled after verification.
+
+The Node base image is pinned by its multi-platform digest. Debian packages and
+transitive npm dependency resolution can still change between builds, so an exact
+CLI version is not a reproducible image digest.
+
+Start the interactive TUI against a project, keeping configuration across runs:
+
+```sh
+docker run --rm -it \
+ --mount type=volume,src=maka-profile,dst=/home/node/.config/Maka \
+ --mount "type=bind,src=$PWD,dst=/workspace" \
+ maka-cli:local
+```
+
+The image includes Tini for signal forwarding and child reaping. Pass CLI arguments
+after the image, for example `--version`, `--help`, or
+`run "Summarize this project"`. No model credentials are embedded. Use `/setup` and `/mcp` to manage connections and MCP servers.
+
+The default user is `node` (UID/GID 1000), with `/workspace` as its working
+directory. On Linux, give that account write access to the bind-mounted project,
+or build a derivative image with an account matching the project owner. The
+profile volume contains credentials and session state; keep it private. Use a
+separate container profile rather than mounting an actively used desktop profile.
+
+For preconfiguration, the default workspace is
+`/home/node/.config/Maka/workspaces/default`; its `mcp.json` can be supplied through
+the profile volume. MCP commands execute **inside** the container: install their
+executables in a derivative image and use container paths in configuration. Node,
+Python, Git, SSH and ripgrep are included; arbitrary MCP servers, browsers, Docker
+and systemd are not. Host files are visible only through mounts, and `localhost`
+refers to the container. The image is intended for TUI/CLI runs, not for installing
+a persistent Runtime Host system service inside Docker.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For additional commands, e-mail: commits-help@maka.apache.org