Skip to content

Docker Notes

See: Docker Compose: A Master Guide with Real-Time Examples

Running Multiple Zensical Containers

To orchestrate multiple Docker containers running Zensical, the official and recommended approach is to use Docker Compose.

Docker Compose allows you to define and manage multiple Zensical documentation sites or a blended stack (i.e., Zensical sites combined with a reverse proxy or backend services) using a single docker-compose.yml configuration file.

Multi-Container Setup

The official Zensical image exposes port 8000 by default and utilizes /docs as its working directory. Below is a sample docker-compose.yml structure that runs two distinct Zensical documentation sites simultaneously.

services:
  # Container 1: Zensical documentation
  zensical:
    image: zensical/zensical:latest
    container_name: zensical
    ports:
      - "127.0.0.1:8006:8000"
    volumes:
      - ./zensical-project:/docs
    restart: unless-stopped

  # Container 2: Pond-7 documentation
  pond-7:
    image: zensical/zensical:latest
    container_name: pond-7
    ports:
      - "127.0.0.1:8008:8000"
    volumes:
      - ./pond-7-project:/docs
    restart: unless-stopped

How to Run and Manage the Fleet

Ensure you have your documentation directories (e.g., ./zensical-project and ./pond-7-project) mapped correctly on your host machine. Navigate to the directory containing your docker-compose.yml configuration file and use these essential Docker commands:

  • Start all containers in the background:
    docker compose up -d
  • Check the running status and port mappings:
    docker compose ps
  • View the aggregated logs or isolate logs for a single service:
    docker compose logs -f api-docs
  • Stop and remove the multi-container stack:
    docker compose down
  • List Docker images (Image, ID, Disk Usage, Content Size, In Use):
    docker images
  • Show the currently installed version of Zensical:
    docker exec -it zensical pip show zensical
    Result
    Name: zensical
Version: 0.0.65
Summary: A modern static site generator built by the creators of Material for MkDocs
Home-page: https://github.com/zensical/zensical
Author:
Author-email: Zensical <contributors@zensical.org>
License-Expression: MIT
Location: /usr/local/lib/python3.14/site-packages
Requires: click, deepmerge, jinja2, markdown, pathspec, pygments, pymdown-extensions, pyyaml, tomli
Required-by:

Updating Zensical

See Zensical Releases.

To update the version of Zensical running inside a container:

  1. Open a bash terminal in the directory containing the docker-compose.yml file.
  2. Shut down the container.
  3. Pull the desired version of Zensical from the offical Docker repository.
  4. Bring the container up again.
bash - for a container named 'zensical'
cd /opt/zensical
docker stop zensical
docker pull zensical/zensical:latest
docker compose up -d