Defaults & Resolution Order

Design & output directories are resolved in this order (per flag):

1. CLI option (-d / -o)

2. Environment variable (SDD_DESIGNS_DIR / SDD_OUTPUT_DIR)

3. Conventional path: ./designs (if it exists) for designs; ./sys-design-diagram-output for output (created on demand)

Inside official Docker images, you typically mount:

• /designs – input (read-only recommended)

• /output – generated diagrams

Environment Variables

Core overrides:

• SDD_DESIGNS_DIR – override designs path

• SDD_OUTPUT_DIR – override output path

Mermaid / Puppeteer tuning:

• MERMAID_PUPPETEER_CONFIG – path to injected Puppeteer JSON (set by image to /opt/puppeteer-config.json adding --no-sandbox etc.)

• SDD_MERMAID_EXTRA_ARGS – extra raw arguments appended to mmdc (e.g. --scale 1.2 --theme dark)

Note: If Chromium launch fails (sandbox / missing dependency) a placeholder PNG containing the original Mermaid source is written so pipelines stay green.

Quick Start (Docker)

Create a local directory with your design sources (.puml, .mmd, Python diagrams):

tree my-designs/
my-designs/
  plantuml1.puml
  sequence.mmd
  infra.py

Run all processors (preferred):

docker run --rm -v "$PWD/my-designs:/designs:ro" -v "$PWD/out:/output" ghcr.io/aydabd/sys-design-diagram:latest process-all

Run only PlantUML:

docker run --rm -v "$PWD/my-designs:/designs:ro" -v "$PWD/out:/output" ghcr.io/aydabd/sys-design-diagram:latest plantuml

Override paths with env vars (custom layout):

docker run --rm \
    -e SDD_DESIGNS_DIR=/work/src/designs \
    -e SDD_OUTPUT_DIR=/work/build/diagrams \
    -v "$PWD/my-designs:/work/src/designs:ro" \
    -v "$PWD/out:/work/build/diagrams" \
    ghcr.io/aydabd/sys-design-diagram:latest process-all

Verbose mode:

docker run --rm -v "$PWD/my-designs:/designs:ro" -v "$PWD/out:/output" ghcr.io/aydabd/sys-design-diagram:latest -v process-all

Using docker compose (see compose.yaml):

Compose services provided:

• sdd-process-all - runs all processors on test data

• sdd-plantuml - PlantUML only

• sdd-diagrams - diagrams library only

• sdd-mermaids - Mermaid only (local build variant)

• sdd-build-locally - builds from workspace sources then process-all

Example (rebuild & run everything detached):

docker compose up --build -d sdd-process-all
# or just Mermaid
docker compose up --build sdd-mermaids

Outputs land in the corresponding subdirectories under ./sdd-outputs or ./sdd-local-outputs as defined in the compose file.

Mermaid Rendering Notes

Chromium + mermaid-cli are bundled. A Puppeteer config (/opt/puppeteer-config.json) adds sandbox‑relaxing flags suitable for rootless containers. If you operate in a hardened environment and can enable the system Chromium sandbox (setuid / userns), you may build a derivative image removing --no-sandbox flags.

To append more Mermaid CLI arguments (e.g. scaling, theme):

docker run --rm -e SDD_MERMAID_EXTRA_ARGS="--scale 1.5 --theme dark" \
    -v "$PWD/my-designs:/designs:ro" -v "$PWD/out:/output" ghcr.io/aydabd/sys-design-diagram:latest mermaid

If rendering fails due to a transient headless issue, a placeholder file is created instead of failing the whole run.