Documentation Site Hosting

Overview

Hosting strategy for the Domus Digitalis unified documentation site built by domus-docs.

Current State

Item Status

Build system

Complete (make in domus-docs)

Local preview

make serve → localhost:8000

GitHub Pages

Workflow exists, blocked by private repo tier

Production hosting

Not deployed

Requirements

  • Private access (not public internet)

  • Custom domain: docs.domusdigitalis.dev

  • TLS certificate (Let’s Encrypt or Vault-issued)

  • Auto-deploy on git push (nice to have)

Options

Option 1: Cloudflare Pages (Interim)

Pros:

  • Free tier supports private repos

  • Auto-deploy from GitHub

  • Global CDN

  • Easy setup

Cons:

  • External dependency

  • Data leaves network

Setup:

  1. Connect Cloudflare to GitHub repo

  2. Build command: npm install && npx antora antora-playbook-local.yml

  3. Output directory: build/site

  4. Add custom domain

Option 2: Self-Hosted nginx (Target)

Pros:

  • Full control

  • No external dependencies

  • Internal network only

  • Integrates with existing infrastructure

Cons:

  • Requires VM/container

  • Manual or scripted deploys

Architecture:

domus-docs repo
    ↓ (git push)
CI runner (gitea-01 or dedicated)
    ↓ (build)
nginx VM/container
    ↓ (serves)
https://docs.domusdigitalis.dev

Candidate hosts:

  • kvm-01 - existing hypervisor, add nginx container

  • New lightweight VM - dedicated docs server

  • nas-01 - if web serving available

Option 3: Gitea Pages

Status: Check if enabled on gitea-01

If Gitea Pages is available, deploy directly from Gitea without external services.

Implementation Plan

Phase 1: Cloudflare Pages (Now)

  1. [ ] Create Cloudflare Pages project

  2. [ ] Connect to domus-docs GitHub repo

  3. [ ] Configure build settings

  4. [ ] Test deployment

  5. [ ] Add docs.domusdigitalis.dev DNS (Cloudflare or pfSense)

Phase 2: Self-Hosted (Future)

  1. [ ] Provision nginx VM or container on KVM

  2. [ ] Configure TLS (Let’s Encrypt via certbot or Vault cert)

  3. [ ] Set up deploy script or CI job

  4. [ ] Update DNS to point internally

  5. [ ] Decommission Cloudflare Pages

Local Development

Anywhere with Node.js installed:

# Clone all repos
git clone git@github.com:EvanusModestus/domus-docs.git
git clone git@github.com:EvanusModestus/domus-infra-ops.git
git clone git@github.com:EvanusModestus/domus-ise-linux.git

# Update local playbook paths if needed
vim domus-docs/antora-playbook-local.yml

# Build and serve
cd domus-docs
make serve
# Open http://localhost:8000

Dependencies:

  • Node.js 18+

  • npx

  • d2 (optional, for diagram rendering)

Sharing the Site

Without hosting:

# Build locally
make

# Share the build directory
tar -czf docs-site.tar.gz build/site/

# Recipient extracts and opens index.html

Quick share with Python:

make serve  # serves on 0.0.0.0:8000
# Share your IP:8000 on local network

Related