This is what an AI/RAG pipeline sees when it indexes this page — the same output served at https://camelmind-docs.vercel.app/api/llms/features/offline-package-and-pdf-export.Back to doc

Rendered doc

Prepare Offline Packages and PDFs

Generate downloadable offline packages and master PDFs for a stable documentation version.

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.

Before you begin
  • You must define the version in versions.yml and have stable: true.
  • Install all project dependencies.
  • Install Playwright's Chromium browser: npx playwright install chromium
  • Stop any running development server (npm run dev) before building.

The build script always generates both the ZIP package and PDF, so it requires Chromium even if you only need the offline package.

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.

bash
./scripts/build-offline.sh latest

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

bash
./scripts/build-offline.sh v2

CamelMind writes both artifacts to offline-builds/:

text
offline-builds/
  camelmind-<version>-offline.zip
  camelmind-<version>.pdf
ArtifactDescription
camelmind-<version>-offline.zipSelf-contained offline documentation site.
camelmind-<version>.pdfSingle PDF containing the cover page, table of contents, and all documentation pages.
Note

The build script always generates both artifacts. You cannot generate only the ZIP or only the 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:

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

Mount offline-builds/Bake artifacts into the image
Refresh artifactsNo image rebuild requiredRequires a new image build and deployment
Host access requiredYesNo
Image build timeUnchangedLonger

Option A: Mount offline-builds/ as a volume

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

bash
./scripts/build-offline.sh latest

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

For Docker Compose:

yaml
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.

Warning

Do not install Playwright into the default Alpine-based builder stage. The base Dockerfile uses node:22-alpine, while Playwright's Chromium installation with --with-deps requires an apt-based Linux distribution. Use a separate Debian-based stage for artifact generation.

dockerfile
# 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.

Note

The dedicated stage installs its own npm dependencies and downloads its own copy of Chromium. In testing, a cold build took about 2 minutes: approximately 10 seconds for dependency installation, 30 seconds for the Chromium download, and the remaining time for artifact generation. Docker layer caching speeds up future builds.

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:

bash
./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.

Warning

Treat generated offline packages and PDFs as copies of the full documentation. Distribute them only to users authorized to access the included content.

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.

The build fails because the development server is running

Stop the development server before running the build script:

bash
npm run dev

The offline build performs a production build and static export. During the process, it temporarily moves server-only routes such as /api/download out of app/ and restores them when the build finishes.

A running development server can conflict with these changes.

PDF generation fails

PDF generation requires Playwright's Chromium browser.

Install Chromium before running the build:

bash
npx playwright install chromium

If you are building inside Docker, use the Debian-based artifact-generation stage described above and install Chromium with:

bash
npx playwright install --with-deps chromium
Download icons do not appear

Check the following:

  1. You have defined the version in versions.yml.
  2. The version has stable: true.
  3. The artifact filenames match the version ID.
  4. If you enable authentication, sign in.

CamelMind displays download icons only for stable versions. When you enable authentication, anonymous users cannot see the icons."

The download link returns 404

Check that the generated filenames match the version ID:

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

Then confirm that:

  1. The version ID matches the id field in versions.yml.
  2. The files exist in offline-builds/.
  3. The running server has access to that directory.
  4. For Docker, offline-builds/ is either mounted into the container or copied into the image.

For a volume-mounted deployment, verify the mount points to the same directory used to generate the artifacts:

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

What the AI sees

1> For a complete documentation index, see /llms.txt. To read any public page as Markdown, append .md to the URL.
2 
3CamelMind can generate two downloadable formats for a documentation version:
4 
5- **Offline package:** A self-contained website for browsing documentation without an internet connection.
6- **Master PDF:** A single PDF containing the documentation for printing, sharing, or compliance requirements.
7 
8CamelMind generates both artifacts together and makes them available as downloads from the version selector.
9 
10---
11 
12<Callout type="important" title="Before you begin">
13 
14- You must define the version in `versions.yml` and have `stable: true`.
15- Install all project dependencies.
16- Install Playwright's Chromium browser:
17 `npx playwright install chromium`
18- Stop any running development server (`npm run dev`) before building.
19 
20The build script always generates both the ZIP package and PDF, so it requires Chromium even if you only need the offline package.
21 
22</Callout>
23 
24---
25 
26## Generate the offline package and PDF artifacts with build scripts
27 
28Run the `./scripts/build-offline.sh` build script with the version ID to generate offline ZIP and master PDF artifacts.
29 
30```bash
31./scripts/build-offline.sh latest
32```
33 
34To generate artifacts for a different version, replace `latest` with its version ID:
35 
36```bash
37./scripts/build-offline.sh v2
38```
39 
40CamelMind writes both artifacts to `offline-builds/`:
41 
42```text
43offline-builds/
44 camelmind-<version>-offline.zip
45 camelmind-<version>.pdf
46```
47 
48| Artifact | Description |
49|----------|-------------|
50| `camelmind-<version>-offline.zip` | Self-contained offline documentation site. |
51| `camelmind-<version>.pdf` | Single PDF containing the cover page, table of contents, and all documentation pages. |
52 
53<Callout type="note">
54The build script always generates both artifacts. You cannot generate only the ZIP or only the PDF.
55</Callout>
56 
57---
58 
59## Make offline package and PDF artifacts available for download
60 
61Start or deploy the documentation site to serve downloadable offline packages and PDFs.
62 
63For local development:
64 
65```bash
66npm run dev
67```
68 
69When CamelMind finds matching artifacts in `offline-builds/`, it automatically displays download icons for each stable version in the version selector:
70 
71- **ZIP:** Downloads the offline documentation package.
72- **PDF:** Downloads the master PDF.
73 
74If 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.
75 
76### Make offline package and PDF artifacts available in Docker containers
77 
78Standard Docker container builds do not automatically include generated offline ZIP packages and PDFs from the `offline-builds/` directory.
79 
80A standard `docker build` does not include `offline-builds/`. The default `Dockerfile` copies the documentation source directories, but not generated offline artifacts.
81 
82As 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.
83 
84Choose one of these approaches:
85 
86| | Mount `offline-builds/` | Bake artifacts into the image |
87|---|---|---|
88| Refresh artifacts | No image rebuild required | Requires a new image build and deployment |
89| Host access required | Yes | No |
90| Image build time | Unchanged | Longer |
91 
92### Option A: Mount `offline-builds/` as a volume
93 
94Generate the artifacts on the host, then mount the directory into the running container.
95 
96```bash
97./scripts/build-offline.sh latest
98 
99docker run --rm -p 3000:3000 \
100 -v "$(pwd)/offline-builds:/app/offline-builds" \
101 my-docs
102```
103 
104For Docker Compose:
105 
106```yaml
107services:
108 camelmind:
109 build: .
110 ports:
111 - "3000:3000"
112 volumes:
113 - ./offline-builds:/app/offline-builds
114```
115 
116The 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.
117 
118### Option B: Include offline packages and PDFs in the Docker image
119 
120To 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.
121 
122<Callout type="warning">
123Do not install Playwright into the default Alpine-based builder stage. The base `Dockerfile` uses `node:22-alpine`, while Playwright's Chromium installation with `--with-deps` requires an apt-based Linux distribution. Use a separate Debian-based stage for artifact generation.
124</Callout>
125 
126```dockerfile
127# Dedicated stage for offline artifact generation.
128# Playwright's Chromium requires an apt-based distribution.
129FROM node:22-bookworm-slim AS offline-builder
130 
131WORKDIR /app
132 
133RUN apt-get update && apt-get install -y --no-install-recommends \
134 ca-certificates \
135 zip \
136 curl \
137 python3 \
138 && rm -rf /var/lib/apt/lists/*
139 
140COPY . .
141 
142RUN if [ -f package-lock.json ]; then npm ci; else npm install; fi
143 
144RUN npx playwright install --with-deps chromium
145 
146RUN ./scripts/build-offline.sh latest && ./scripts/build-offline.sh v2
147 
148# Copy generated artifacts into the runtime image.
149COPY --from=offline-builder --chown=nextjs:nodejs /app/offline-builds ./offline-builds
150```
151 
152The artifact build requires `zip`, `python3`, and `curl` because `build-offline.sh` uses these commands to:
153 
154- create the offline ZIP
155- serve the static export for PDF generation
156- poll the local server while generating the PDF
157 
158Without these dependencies, the build fails.
159 
160<Callout type="note">
161The dedicated stage installs its own npm dependencies and downloads its own copy of Chromium. In testing, a cold build took about 2 minutes: approximately 10 seconds for dependency installation, 30 seconds for the Chromium download, and the remaining time for artifact generation. Docker layer caching speeds up future builds.
162</Callout>
163 
164This approach makes the Docker image self-contained: every deployment includes the generated offline package and PDF.
165 
166See [Docker Self-Hosting](/deployment/docker-self-hosting) for the rest of the Docker configuration, including Compose, reverse proxy, and environment variables.
167 
168---
169 
170## Keep offline package and PDF artifacts up to date across updates
171 
172To maintain current downloads when documentation content changes, run the build script to regenerate offline ZIP packages and master PDFs:
173 
174```bash
175./scripts/build-offline.sh <version>
176```
177 
178For production deployments, include artifact generation in your CI/CD pipeline.
179 
180If you mount `offline-builds/` as a volume, regenerate the files on the host and make the updated directory available to the container.
181 
182If you bake the artifacts into the Docker image, regenerate them as part of the image build and deploy the new image.
183 
184---
185 
186## Protect generated artifacts and security access
187 
188Because 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.
189 
190<Callout type="warning">
191Treat generated offline packages and PDFs as copies of the full documentation. Distribute them only to users authorized to access the included content.
192</Callout>
193 
194---
195 
196## Troubleshoot offline package and PDF generation errors
197 
198Resolve common build failures, missing download icons, 404 errors, and Playwright Chromium browser issues when exporting offline packages and PDFs.
199 
200<Details summary="The build fails because the development server is running" id="offline-pdf-faq1">
201 
202Stop the development server before running the build script:
203 
204```bash
205npm run dev
206```
207 
208The offline build performs a production build and static export. During the process, it temporarily moves server-only routes such as `/api/download` out of `app/` and restores them when the build finishes.
209 
210A running development server can conflict with these changes.
211 
212</Details>
213 
214<Details summary="PDF generation fails" id="offline-pdf-faq2">
215 
216PDF generation requires Playwright's Chromium browser.
217 
218Install Chromium before running the build:
219 
220```bash
221npx playwright install chromium
222```
223 
224If you are building inside Docker, use the Debian-based artifact-generation stage described above and install Chromium with:
225 
226```bash
227npx playwright install --with-deps chromium
228```
229 
230</Details>
231 
232<Details summary="Download icons do not appear" id="offline-pdf-faq3">
233 
234Check the following:
235 
2361. You have defined the version in `versions.yml`.
2372. The version has `stable: true`.
2383. The artifact filenames match the version ID.
2394. If you enable authentication, sign in.
240 
241CamelMind displays download icons only for stable versions. When you enable authentication, anonymous users cannot see the icons."
242 
243</Details>
244 
245<Details summary="The download link returns 404" id="offline-pdf-faq4">
246 
247Check that the generated filenames match the version ID:
248 
249```text
250camelmind-<version>-offline.zip
251camelmind-<version>.pdf
252```
253 
254Then confirm that:
255 
2561. The version ID matches the `id` field in `versions.yml`.
2572. The files exist in `offline-builds/`.
2583. The running server has access to that directory.
2594. For Docker, `offline-builds/` is either mounted into the container or copied into the image.
260 
261For a volume-mounted deployment, verify the mount points to the same directory used to generate the artifacts:
262 
263```bash
264-v "$(pwd)/offline-builds:/app/offline-builds"
265```
266 
267</Details>

Issues (0)

No AI-friendliness issues found.