Build Sites with a Container

Use the builder container when Python should not be installed directly on the host. The private Markdown is mounted read-only, and generated files are written to a separate host directory.

Build the builder image#

Run this command from the Simple Docs repository:

podman build \
  --target builder \
  -t simple-docs-builder \
  -f Containerfile .

The builder image contains Python, build.py, VERSION, shared assets, and the bundled themes. It does not contain bundled or private documentation source.

Select a theme#

Pass the theme name to the builder command:

--theme paper

To bake the paper theme into the bundled nginx example, use:

podman build \
  --build-arg THEME=paper \
  -t simple-docs-paper \
  -f Containerfile .

Docker accepts the same build argument. See create and select themes for available themes and the authoring contract.

Generate a site with Podman#

Create an output parent directory:

mkdir -p /absolute/path/to/private-project-build

Run the builder with two bind mounts:

podman run --rm --userns=keep-id \
  -v /absolute/path/to/private-project/docs:/input:ro,Z \
  -v /absolute/path/to/private-project-build:/output:Z \
  simple-docs-builder \
  --source /input \
  --output /output/site \
  --archive /output/manual-site.tar.gz

The /input mount is read-only. The builder can write only to /output and temporary locations inside the container.

The :Z suffix applies a private SELinux label for Podman. Omit :Z on systems that do not use SELinux labeling.

Generate an offline ZIP#

The same builder can create a ZIP that opens without a server. Add this option to the Podman or Docker command:

--offline-archive /output/manual-site-offline.zip

The ZIP is written through the existing /output bind mount. Extract it and open manual-site-offline/index.html.

Generate a site with Docker#

Build the same target:

docker build \
  --target builder \
  -t simple-docs-builder \
  -f Containerfile .

Run it with the host user identity so generated files are not owned by root:

docker run --rm --user "$(id -u):$(id -g)" \
  -v /absolute/path/to/private-project/docs:/input:ro \
  -v /absolute/path/to/private-project-build:/output \
  simple-docs-builder \
  --source /input \
  --output /output/site \
  --archive /output/manual-site.tar.gz

Build for a URL prefix#

Pass the base path after the output options:

podman run --rm --userns=keep-id \
  -v /absolute/path/to/private-project/docs:/input:ro,Z \
  -v /absolute/path/to/private-project-build:/output:Z \
  simple-docs-builder \
  --source /input \
  --output /output/site \
  --archive /output/manual-site.tar.gz \
  --base-path /project-name/

Verify source isolation#

The generated site/ directory and archives contain generated files, not Markdown. The private source is not copied into the builder image or nginx runtime image.

Return to the generating sites overview, compare the Python workflow, use the Make helpers, or continue with serving generated sites. You can also create or select a theme.