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

> Learn how to run OfficeCLI in Docker for streamlined document workflows. This guide covers automatic Docker detection and containerized setup for iOfficeAI/OfficeCLI.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: how-to-guide
- Published: 2026-07-10

---

**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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.

```dockerfile

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

# 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:

```bash

# 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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.