Prepare Offline Packages and PDFs

CamelMind can generate two downloadable formats for a documentation version:

• Offline package: A self-contained website for browsing documentation without an internet connection.
• Master PDF: A single PDF containing the documentation for printing, sharing, or compliance requirements.

CamelMind generates both artifacts together and makes them available as downloads from the version selector.

Generate the offline package and PDF artifacts with build scripts

Run the ./scripts/build-offline.sh build script with the version ID to generate offline ZIP and master PDF artifacts.

./scripts/build-offline.sh latest

To generate artifacts for a different version, replace latest with its version ID:

./scripts/build-offline.sh v2

CamelMind writes both artifacts to offline-builds/:

offline-builds/
  camelmind-<version>-offline.zip
  camelmind-<version>.pdf

Make offline package and PDF artifacts available for download

Start or deploy the documentation site to serve downloadable offline packages and PDFs.

For local development:

npm run dev

When CamelMind finds matching artifacts in offline-builds/, it automatically displays download icons for each stable version in the version selector:

• ZIP: Downloads the offline documentation package.
• PDF: Downloads the master PDF.

If you enable authentication with CAMELMIND_AUTH_ENABLED=true, only signed-in users see the download icons. When you disable authentication, the icons are visible to everyone.

Make offline package and PDF artifacts available in Docker containers

Standard Docker container builds do not automatically include generated offline ZIP packages and PDFs from the offline-builds/ directory.

A standard docker build does not include offline-builds/. The default Dockerfile copies the documentation source directories, but not generated offline artifacts.

As a result, a deployed container can display the download icons but return 404 from /api/download unless you explicitly make offline-builds/ available to the container.

Choose one of these approaches:

Option A: Mount offline-builds/ as a volume

Generate the artifacts on the host, then mount the directory into the running container.

./scripts/build-offline.sh latest

docker run --rm -p 3000:3000 \
  -v "$(pwd)/offline-builds:/app/offline-builds" \
  my-docs

For Docker Compose:

services:
  camelmind:
    build: .
    ports:
      - "3000:3000"
    volumes:
      - ./offline-builds:/app/offline-builds

The container reads the files from offline-builds/ when handling download requests. To update the downloads, run the build script again on the host. You do not need to rebuild or restart the container.

Option B: Include offline packages and PDFs in the Docker image

To build offline ZIP packages and master PDFs directly into your container image, use a dedicated Debian-based Docker build stage to generate and store these artifacts during the image build process.

# Dedicated stage for offline artifact generation.
# Playwright's Chromium requires an apt-based distribution.
FROM node:22-bookworm-slim AS offline-builder

WORKDIR /app

RUN apt-get update && apt-get install -y --no-install-recommends \
    ca-certificates \
    zip \
    curl \
    python3 \
  && rm -rf /var/lib/apt/lists/*

COPY . .

RUN if [ -f package-lock.json ]; then npm ci; else npm install; fi

RUN npx playwright install --with-deps chromium

RUN ./scripts/build-offline.sh latest && ./scripts/build-offline.sh v2

# Copy generated artifacts into the runtime image.
COPY --from=offline-builder --chown=nextjs:nodejs /app/offline-builds ./offline-builds

The artifact build requires zip, python3, and curl because build-offline.sh uses these commands to:

• create the offline ZIP
• serve the static export for PDF generation
• poll the local server while generating the PDF

Without these dependencies, the build fails.

This approach makes the Docker image self-contained: every deployment includes the generated offline package and PDF.

See Docker Self-Hosting for the rest of the Docker configuration, including Compose, reverse proxy, and environment variables.

Keep offline package and PDF artifacts up to date across updates

To maintain current downloads when documentation content changes, run the build script to regenerate offline ZIP packages and master PDFs:

./scripts/build-offline.sh <version>

For production deployments, include artifact generation in your CI/CD pipeline.

If you mount offline-builds/ as a volume, regenerate the files on the host and make the updated directory available to the container.

If you bake the artifacts into the Docker image, regenerate them as part of the image build and deploy the new image.

Protect generated artifacts and security access

Because offline package and PDF builds bypass authentication, the build process includes all documentation pages in the generated ZIP and PDF files regardless of web application access controls.

Troubleshoot offline package and PDF generation errors

Resolve common build failures, missing download icons, 404 errors, and Playwright Chromium browser issues when exporting offline packages and PDFs.

npm run dev

npx playwright install chromium

npx playwright install --with-deps chromium

camelmind-<version>-offline.zip
camelmind-<version>.pdf

-v "$(pwd)/offline-builds:/app/offline-builds"