feat: pf-4298 build, run container

* containerfile, multi-stage node 24 build
* docs, new container run section, examples
* config, container example
* package.json, container:build and container:start scripts
* scripts, build image, run container

Author: cdcabrera

.containerignore

@@ -0,0 +1,8 @@
+# Ignore everything by default
+*
+
+# Allowlist only the files and directories required for the build context
+!package.json
+!package-lock.json
+!tsconfig.json
+!src/

Containerfile

@@ -0,0 +1,84 @@
+#
+# PatternFly MCP server — container image definition.
+#
+# Multi-stage build. Produces a minimal Node.js 24 runtime image that
+# launches the MCP server as a stdio process; HTTP transport is
+# available by passing `--http --port <n>` at `podman run` time (the
+# `ENTRYPOINT` forwards all arguments verbatim to the CLI).
+#
+# Base image: UBI 9 Node.js 24 minimal.
+#   - Anonymous pull from `registry.access.redhat.com` (no login required).
+#   - glibc-based, rootless-friendly, sets `APP_ROOT=/opt/app-root` and a
+#     default non-root user at UID 1001.
+#
+#
+# ---- Stage 1: builder ---------------------------------------------------
+# Installs deps, compiles the bundle with pkgroll, and prunes dev deps so
+# only the runtime payload moves into stage 2.
+FROM registry.access.redhat.com/ubi9/nodejs-24-minimal:latest AS builder
+
+# Non-root build/runtime user. Matches the UBI base default; exposed as an
+# ARG so downstream tooling can override without editing the file.
+ARG CONTAINER_UID=1001
+ENV CONTAINER_UID=${CONTAINER_UID}
+
+# UBI defines `APP_ROOT=/opt/app-root`; reuse it so paths line up with the
+# base image's conventions.
+WORKDIR ${APP_ROOT}
+
+# Copy only the files needed to resolve deps first.
+COPY --chown=${CONTAINER_UID}:0 package.json package-lock.json tsconfig.json ./
+
+USER ${CONTAINER_UID}
+
+# Lockfile-exact install.
+RUN npm ci --ignore-scripts --no-audit --no-fund
+
+# Copy the rest of the source and produce the bundle.
+COPY --chown=${CONTAINER_UID}:0 src ./src
+RUN npx --no-install pkgroll --minify \
+ && npm prune --omit=dev --ignore-scripts
+
+# ---- Stage 2: runtime ---------------------------------------------------
+# Minimal runtime image. Only the compiled bundle, pruned `node_modules`,
+# and `package.json` are carried over from the builder stage.
+FROM registry.access.redhat.com/ubi9/nodejs-24-minimal:latest AS runtime
+
+# Standard OCI annotations
+LABEL org.opencontainers.image.title="patternfly-mcp" \
+      org.opencontainers.image.description="PatternFly documentation MCP server (Node.js 24)" \
+      org.opencontainers.image.source="https://github.com/patternfly/patternfly-mcp" \
+      org.opencontainers.image.url="https://github.com/patternfly/patternfly-mcp" \
+      org.opencontainers.image.licenses="MIT" \
+      org.opencontainers.image.vendor="Red Hat" \
+      io.modelcontextprotocol.transport="stdio"
+
+# Re-declare the build arg in this stage. ARGs do not cross stages.
+ARG CONTAINER_UID=1001
+ENV CONTAINER_UID=${CONTAINER_UID}
+
+# Runtime environment defaults:
+#   - `NODE_ENV=production`           enables production code paths in deps
+#   - `NPM_CONFIG_UPDATE_NOTIFIER`    suppress npm self-update nags
+#   - `NO_COLOR`                      keep stderr/stdout machine-readable
+#                                     (MCP clients consume these streams)
+ENV NODE_ENV=production \
+    NPM_CONFIG_UPDATE_NOTIFIER=false \
+    NO_COLOR=1
+
+WORKDIR ${APP_ROOT}
+
+# Runtime payload
+COPY --from=builder --chown=${CONTAINER_UID}:0 ${APP_ROOT}/package.json   ${APP_ROOT}/package.json
+COPY --from=builder --chown=${CONTAINER_UID}:0 ${APP_ROOT}/node_modules   ${APP_ROOT}/node_modules
+COPY --from=builder --chown=${CONTAINER_UID}:0 ${APP_ROOT}/dist           ${APP_ROOT}/dist
+
+USER ${CONTAINER_UID}
+
+# stdio MCP server by default. Clients attach over stdin/stdout. `CMD`
+# provides only a default flag set; anything passed after the image name
+# on `podman run ... <image> <flags>` replaces `CMD` entirely, so every
+# CLI option (including `--http --port <n>` for HTTP transport) works
+# without rebuilding the image.
+ENTRYPOINT ["node", "dist/cli.js"]
+CMD ["--log-stderr"]

cspell.config.json

@@ -3,6 +3,7 @@
   "words": [
     "amet",
     "codemods",
+    "containerfile",
     "deprioritized",
     "ized",
     "llms",
@@ -16,13 +17,17 @@
     "prefault",
     "rereview",
     "rescan",
+    "rootfs",
     "rsort",
+    "sandboxed",
     "sandboxing",
     "sparkline",
     "streamable",
+    "tmpfs",
     "treeify",
     "unrepresentable",
     "unsub",
-    "untampered"
+    "untampered",
+    "userns"
   ]
 }

docs/usage.md

@@ -6,6 +6,7 @@ A comprehensive guide to PatternFly MCP Server tools, resources, and configurati
 - [Built-in tools](#built-in-tools)
 - [Built-in resources](#built-in-resources)
 - [MCP client configuration](#mcp-client-configuration)
+- [Running via container](#running-via-container-podman--docker)
 - [Custom MCP tool plugins](#custom-mcp-tool-plugins)
 - [Experimental settings](./experimental.md)
 - [Troubleshooting](#troubleshooting)
@@ -200,6 +201,122 @@ Depending on your environment, you may have to delay updating to the minimum Nod
 }
 ```
 
+### Running via container (podman)
+
+The server can also be launched from a container image instead of `npx`. This is useful when you want a pinned, sandboxed runtime that doesn't depend on the host's Node.js installation. Running with an MCP client simply spawns `podman` (or `docker`) instead of `npx`.
+
+> **Prerequisites:**
+> You can use Podman or Docker to run the container.
+>
+> We recommend using Podman Desktop for convenience:
+> - [Podman Desktop](https://podman-desktop.io/downloads)
+> - [Podman](https://podman.io/)
+
+#### Build the image locally
+
+From the repository root:
+
+```bash
+bash ./scripts/container/build.sh
+```
+
+or using Node.js and NPM:
+
+```
+npm run build:container
+```
+
+This produces the following images:
+- `localhost/patternfly-mcp:<version>`,
+- `localhost/patternfly-mcp:<version>-node24`,
+- `localhost/patternfly-mcp:sha-<short>`
+- `localhost/patternfly-mcp:latest`.
+
+You can confirm by running `$ podman images` from the terminal. View the [Containerfile](../Containerfile) for the image definition.
+
+#### Running your local image, MCP client configuration
+
+```json
+{
+  "mcpServers": {
+    "patternfly-mcp": {
+      "command": "podman",
+      "args": [
+        "run", "--rm", "-i",
+        "--userns=keep-id",
+        "--security-opt=no-new-privileges",
+        "--cap-drop=ALL",
+        "localhost/patternfly-mcp:latest",
+        "--log-stderr"
+      ],
+      "description": "PatternFly rules and documentation (local container)"
+    }
+  }
+}
+```
+
+> **Important**:
+> - `-i` (interactive stdin) is **required** for stdio MCP. Do **not** pass `-t`. Anything appended after the image name is forwarded verbatim to the CLI, so every flag (`--verbose`, `--http`, `--port`, `--tool`, ...) works without rebuilding.
+> - The same configuration should work with `docker`, just replace `"command": "podman"` with `"command": "docker"`.
+
+#### Smoke test
+
+```bash
+podman run --rm localhost/patternfly-mcp:latest node -e "console.log(process.versions.node)"  # -> 24.x
+```
+
+#### Running in HTTP transport mode
+
+The image's `ENTRYPOINT` forwards every argument straight to the CLI, so HTTP mode works against the **same image** with no rebuild — just publish a port and pass `--http --port`.
+
+```bash
+podman run --rm \
+  --userns=keep-id \
+  --security-opt=no-new-privileges \
+  --cap-drop=ALL \
+  --read-only \
+  --tmpfs /tmp:rw,size=64m \
+  -p 3030:8080 \
+  localhost/patternfly-mcp:latest \
+  --http --port 8080 \
+  --allowed-origins "http://127.0.0.1:3030" \
+  --allowed-hosts  "127.0.0.1" \
+  --log-stderr
+```
+
+Notes:
+- `-p <host>:<container>` publishes the port. The container-side port (`8080` above) must match `--port`. The host-side port is whatever you want clients to connect to.
+- `8080` inside the container matches the port the UBI Node.js base already advertises via `EXPOSE`, and a non-root user can bind it without extra capabilities.
+- `-i` (interactive stdin) is **not** required in HTTP mode and is omitted here.
+- `--allowed-origins` and `--allowed-hosts` are required guardrails when the server is reachable beyond stdio; set them explicitly.
+- `--read-only` is safe today because the server writes nothing to the rootfs (only `/tmp`, which is a tmpfs). When the persistent SQLite cache lands, you will need to either drop `--read-only` or mount a writable volume for the cache directory.
+- TLS is out of scope for the image itself. For anything beyond `localhost`, terminate TLS at a reverse proxy (Caddy, nginx, an OpenShift route, etc.).
+
+##### MCP client configuration (HTTP)
+
+HTTP MCP clients connect via URL rather than spawning a process. Start the container separately (e.g. with the command above, `podman-compose`, or a systemd unit) and point the client at the published host port:
+
+```json
+{
+  "mcpServers": {
+    "patternfly-mcp": {
+      "url": "http://localhost:3030",
+      "description": "PatternFly rules and documentation (HTTP transport, containerized)"
+    }
+  }
+}
+```
+
+> Stdio-only MCP clients should keep using the [stdio container configuration above](#running-your-local-image-mcp-client-configuration); the HTTP form requires a client that supports HTTP/SSE MCP transports.
+
+##### Verify it's listening
+
+```bash
+curl -sS -i http://localhost:3030/ | head -20
+```
+
+`--log-stderr` will print the registered routes at startup, which is the easiest way to confirm the server bound the expected port.
+
 ## Custom MCP tool plugins
 
 You can extend the server's capabilities by loading custom **Tool Plugins** at startup.

mcp-config-container-example.json

@@ -0,0 +1,16 @@
+{
+  "mcpServers": {
+    "patternfly-mcp": {
+      "command": "podman",
+      "args": [
+        "run", "--rm", "-i",
+        "--userns=keep-id",
+        "--security-opt=no-new-privileges",
+        "--cap-drop=ALL",
+        "localhost/patternfly-mcp:latest",
+        "--log-stderr"
+      ],
+      "description": "PatternFly rules and documentation (local container)"
+    }
+  }
+}

package.json

@@ -28,6 +28,8 @@
     "build": "npm run build:clean; npm run test:types; pkgroll",
     "build:clean": "rm -rf dist",
     "build:watch": "npm run build -- --watch",
+    "container:build": "bash ./scripts/container.build.sh",
+    "container:start": "bash ./scripts/container.run.sh",
     "release": "changelog --non-cc --link-url https://github.com/patternfly/patternfly-mcp.git",
     "start": "node dist/cli.js --log-stderr",
     "start:dev": "tsx watch src/cli.ts --verbose --log-stderr",

scripts/container.build.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# Build the PatternFly MCP container image locally from the repository's
+# Containerfile. Podman is the primary, supported runtime; Docker is
+# detected as a fallback only if Podman is not installed.
+#
+# Produces four tags under the `${IMAGE}` repository:
+#   - ${IMAGE}:<semver>           (from package.json#version)
+#   - ${IMAGE}:<semver>-node24    (Node.js 24 base image identifier)
+#   - ${IMAGE}:sha-<git short>    (current HEAD short SHA, or `dev` outside git)
+#   - ${IMAGE}:latest
+#
+# Usage:
+#   ./scripts/container.build.sh
+#   IMAGE=localhost/patternfly-mcp ./scripts/container.build.sh
+#
+# Environment:
+#   IMAGE  Image repository (without tag). Defaults to `localhost/patternfly-mcp`.
+#
+# main()
+#
+{
+  # Fail fast on errors, unset variables, and broken pipes.
+  set -euo pipefail
+
+  # Derive tag metadata from package.json and git. `SHA` falls back to `dev`
+  # when invoked outside a git checkout (e.g. extracted tarball).
+  VERSION="$(node -p "require('./package.json').version")"
+  SHA="$(git rev-parse --short HEAD 2>/dev/null || echo dev)"
+  IMAGE="${IMAGE:-localhost/patternfly-mcp}"
+  ENGINE=""
+
+  # Prefer podman. Docker is supported but intentionally not advertised; if
+  # neither runtime is available, fail with a clear error.
+  if [ "$(command -v podman)" ]; then
+    ENGINE="podman"
+  elif [ "$(command -v docker)" ]; then
+    ENGINE="docker"
+  else
+    echo 'Error: Podman and Docker not found.' >&2
+    exit 1
+  fi
+
+  echo "Using $ENGINE...";
+
+  # Build with all four tags applied in a single pass so the layer cache is
+  # shared and the tags are guaranteed to reference the same image digest.
+  "$ENGINE" build \
+    --file Containerfile \
+    --tag "${IMAGE}:${VERSION}" \
+    --tag "${IMAGE}:${VERSION}-node24" \
+    --tag "${IMAGE}:sha-${SHA}" \
+    --tag "${IMAGE}:latest" \
+    .
+
+  # Echo the resulting tag set so callers (and CI logs) can see exactly what
+  # was produced without re-running `podman images`.
+  echo
+  echo "Built tags:"
+  echo "  ${IMAGE}:${VERSION}"
+  echo "  ${IMAGE}:${VERSION}-node24"
+  echo "  ${IMAGE}:sha-${SHA}"
+  echo "  ${IMAGE}:latest"
+}