Running OfficeCLI in Docker: A Complete Guide to Containerized Document Workflows

OfficeCLI automatically detects Docker environments by checking for the /.dockerenv file and adjusts its behavior to skip interactive prompts, use writable installation paths, and expose the preview server on all interfaces.

OfficeCLI from the iOfficeAI/OfficeCLI repository is a self-contained binary that bundles the .NET runtime and all native dependencies, making it ideal for containerized workflows. Because it requires no additional packages, you can deploy it in minimal Docker images for CI/CD pipelines, automated report generation, or isolated document editing microservices.

How OfficeCLI Detects Docker Environments

The container detection logic resides in src/officecli/Core/UpdateChecker.cs at lines 567-578. According to the source code, OfficeCLI checks for the presence of the /.dockerenv file—a convention used by Docker and many Kubernetes runtimes—to determine if it is running inside an OCI container.

When this file exists, OfficeCLI enables container-specific defaults that prevent interactive blocking and ensure compatibility with restricted filesystems.

Container-Specific Behavior Modifications

Once Docker detection occurs, OfficeCLI modifies three key behaviors:

Non-Interactive Update Checks

The application performs background update checks but skips interactive prompts that would otherwise block startup waiting for user input. This ensures headless containers start without hanging.

Read-Only Filesystem Handling

When running in a container, the --install command installs the binary under a writable path such as $HOME/.local/bin rather than the system's default location. This supports read-only root filesystem deployments common in Kubernetes security contexts.

HTTP Preview Server Binding

The officecli watch command exposes a built-in HTTP preview server that binds to all interfaces (0.0.0.0) when the OFFICECLI_BIND_ALL environment variable is set. This enables external access to the live preview from outside the container.

Building a Minimal OfficeCLI Docker Image

Because OfficeCLI bundles all dependencies, you only need to copy the binary into a minimal base image. The following multi-stage Dockerfile pattern works for both Linux x64 and ARM64 architectures, verifies SHA-256 checksums, and supports AI agent workflows.

# ------------------------------------------------------------

# 1️⃣  Build‑time stage – fetch the correct binary for the platform

# ------------------------------------------------------------

FROM alpine:3.19 AS downloader
ARG VERSION=v6.3.1    # set to the desired release tag

ARG ASSET=officecli-linux-x64   # change to officecli-linux-arm64 on ARM

# Install curl and ca‑certificates (required for HTTPS)

RUN apk add --no-cache curl ca-certificates

# Download the binary and its checksum from the official mirror

RUN curl -fsSL https://d.officecli.ai/releases/download/${VERSION}/${ASSET} -o /tmp/officecli && \
    curl -fsSL https://d.officecli.ai/releases/download/${VERSION}/SHA256SUMS -o /tmp/SHA256SUMS && \
    # Verify checksum (exact filename match)

    EXPECTED=$(awk -v a="${ASSET}" '$2 == a {print $1; exit}' /tmp/SHA256SUMS) && \
    ACTUAL=$(sha256sum /tmp/officecli | awk '{print $1}') && \
    [ "$EXPECTED" = "$ACTUAL" ]

# ------------------------------------------------------------

# 2️⃣  Runtime stage – tiny Alpine image with the binary installed

# ------------------------------------------------------------

FROM alpine:3.19
ARG ASSET=officecli-linux-x64

# Copy the verified binary from the previous stage

COPY --from=downloader /tmp/officecli /usr/local/bin/officecli
RUN chmod +x /usr/local/bin/officecli

# Optional: expose the preview server port (default 26315)

EXPOSE 26315

# Default command – start a resident session that watches a document

# Change “demo.pptx” to any file you want to edit inside the container.

ENTRYPOINT ["officecli", "watch", "demo.pptx"]

Build and run the container using these commands:

# Build the image (replace the tag with the desired version)

docker build -t officecli:latest .

# Start a container, mounting a host directory that contains your document

docker run --rm -it \
  -v $(pwd)/demo:/data \
  -w /data \
  -p 26315:26315 \
  officecli:latest

The document demo.pptx (or any .docx or .xlsx file) is edited from inside the container, with the live preview reachable at http://localhost:26315. If you need a read-only root filesystem, add --read-only to the docker run command; OfficeCLI will continue functioning because it writes only to the mounted volume (/data).

Key Configuration Options for Docker Deployments

Consider these practices when deploying OfficeCLI in production container environments:

• Writable Location: Always mount a host volume (-v) and allow OfficeCLI to write temporary files there, using the $HOME/.local/bin fallback for installations.
• Port Exposure: The preview server runs on port 26315 by default; expose it via -p or configure a custom port with --watch-port.
• Checksum Verification: The install.sh script validates SHA-256 hashes. Reuse this logic in your Dockerfile to guarantee binary integrity.
• Multi-Architecture Images: Use build-time arguments (ASSET) to select officecli-linux-x64 or officecli-linux-arm64. CI pipelines can produce both variants and push them to a single multi-arch manifest.
• Environment Variables: Set OFFICECLI_SKIP_UPDATE=1 to disable background update checks for deterministic CI runs, or OFFICECLI_BIND_ALL to enable external preview access.

Summary

• OfficeCLI detects Docker via the /.dockerenv file in UpdateChecker.cs (lines 567-578).
• Container mode skips interactive prompts, uses writable paths for installations, and supports read-only root filesystems.
• The built-in preview server binds to 0.0.0.0 when OFFICECLI_BIND_ALL is set, defaulting to port 26315.
• No .NET runtime or dependencies are required inside the image, enabling minimal Alpine-based containers.
• Verify binary integrity using the SHA-256 checksums provided in the official release mirror.

Frequently Asked Questions

How does OfficeCLI detect it is running inside a Docker container?

According to the source code in src/officecli/Core/UpdateChecker.cs at lines 567-578, OfficeCLI checks for the existence of the /.dockerenv file. This is a standard convention used by Docker and many Kubernetes runtimes to indicate an OCI container environment.

Can I run OfficeCLI with a read-only root filesystem?

Yes. When OfficeCLI detects a container environment, it automatically adjusts the --install command to use writable paths such as $HOME/.local/bin instead of system directories. For read-only deployments, ensure you mount a writable volume (e.g., -v /data:/data) where OfficeCLI can write temporary files.

What port does the OfficeCLI preview server use in Docker?

The preview server defaults to port 26315. When running in Docker with OFFICECLI_BIND_ALL set, the server binds to 0.0.0.0:26315 to allow external access. You can customize this using the --watch-port flag or by mapping a different host port with Docker's -p option.

Do I need to install .NET runtime in the Docker image?

No. OfficeCLI is a self-contained binary that bundles the .NET runtime and all required native libraries. The minimal Dockerfile only needs a base image like Alpine Linux and the compiled binary, with no additional runtime dependencies required.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}