Deployment & Distribution

Deployment & Distribution

The UI bundle is built by Cloudflare Pages and distributed to the docs aggregator via Cloudflare Access-authenticated HTTPS.

Cloudflare Pages (ui.domusdigitalis.dev)

The domus-antora-ui repo is connected to Cloudflare Pages:

Setting Value

Build command

npm run build

Output directory

build

Node version

>= 16.0.0

Trigger

Push to main branch

URL

ui.domusdigitalis.dev

Key output

ui.domusdigitalis.dev/ui-bundle.zip

The npm run build script runs gulp bundle && cp -r static/* build/, producing the bundle plus any static assets (landing page, etc.) in the build/ directory.

Cloudflare Access Authentication

The bundle URL is protected by Cloudflare Zero Trust Access:

  • Application: Configured in CF Zero Trust > Access > Applications

  • Policy: Service token authentication (no interactive login)

  • Headers required:

    • CF-Access-Client-Id: <service-token-id>

    • CF-Access-Client-Secret: <service-token-secret>

Without valid CF Access headers, ui.domusdigitalis.dev returns a 403. The service tokens are stored as Cloudflare Pages environment variables in the domus-docs project.

build.sh CI Flow

The domus-docs/build.sh script (run by Cloudflare Pages CI) performs:

  1. Fetch bundle: curl with CF Access headers downloads ui-bundle.zip from ui.domusdigitalis.dev

  2. Validate bundle: unzip -t verifies zip integrity, grep confirms domus-theme.css is present

  3. Inject auth: sed replaces GitHub URL prefixes with PAT-authenticated URLs using CF_ANTORA_GIT_TOKEN

  4. Build site: npx antora --quiet antora-playbook.yml

Environment variables required:

Variable Purpose

CF_ACCESS_CLIENT_ID

Cloudflare Access service token ID

CF_ACCESS_CLIENT_SECRET

Cloudflare Access service token secret

CF_ANTORA_GIT_TOKEN

GitHub PAT for private repo access during Antora build

Local Development Workflow

For local builds, the bundle is referenced by filesystem path:

# 1. Build the UI bundle
cd ~/atelier/_bibliotheca/domus-antora-ui
make

# 2. Build the docs site with the local bundle
cd ~/atelier/_bibliotheca/domus-docs
make

The local playbook (antora-playbook-local.yml) points directly to the build output:

ui:
  bundle:
    url: /home/evanusmodestus/atelier/_bibliotheca/domus-antora-ui/build/ui-bundle.zip
    snapshot: true

snapshot: true ensures Antora always reads the latest bundle, even if the file path hasn’t changed.

Git Mirrors

The repository is mirrored across three platforms:

Platform URL

GitHub (primary)

github.com/EvanusModestus/domus-antora-ui

GitLab

gitlab.com/EvanusModestus/domus-antora-ui

Gitea

git.domusdigitalis.dev/evan/domus-antora-ui

Bundle Versioning

  • package.json version: 1.0.0

  • Bundle is not semantically versioned for distribution — snapshot: true bypasses caching

  • Cloudflare Pages provides unique deploy URLs per build for rollback capability

  • .gitlab-ci.yml exists for GitLab CI (secondary pipeline)