Deploying the wiki (Coolify)

Deploying the wiki (Coolify)

The wiki is a static Astro Starlight build (wiki-site/), generated from this repo’s docs/, specs/, and contracts/ on every build. Self-hosted on Coolify.

Prerequisites

1. Git remote. Coolify deploys from a git source — push this repo to GitHub / GitLab / Gitea that the Coolify instance can read.
2. Commit wiki-site/pnpm-lock.yaml so installs are reproducible (--frozen-lockfile).

Coolify settings (Dockerfile build pack)

Use the Dockerfile build pack — the repo ships a Dockerfile + nginx.conf at the root.

Field	Value
Build pack	Dockerfile
Base directory	/ (repo root — do not set /wiki-site)
Dockerfile location	Dockerfile (root)
Port	80

Push to the deploy branch → Coolify rebuilds → wiki updates (publish-on-commit).

Why not a /wiki-site base directory + Nixpacks? Setting the base directory to the subdir makes the build context only wiki-site/, so the build can’t see ../docs, ../specs, ../contracts and fails with ENOENT on every contract + an empty sync. The Dockerfile builds from the whole repo (context = root), runs the build inside wiki-site/ (where ../ resolves), then serves dist/ with nginx. The nginx.conf handles Starlight’s directory-style routes + the 404 page.

Access control — required

The wiki describes internal architecture, the data model, tenancy, and GDPR posture. It must not be a public URL. Put one of these in front, easiest first:

• HTTP Basic Auth via Coolify/Traefik labels — quick, fine for a small team.
• Authelia / Authentik forward-auth middleware — proper SSO, can tie to Google Workspace.
• VPN / internal-network only — if the Coolify host isn’t publicly exposed.

Do not deploy it reachable without one of these.