WORKSPACE

Several repos, one site, behind a login

Run vibeX once from the folder above your repos. It finds every repo's specs and builds one site: a landing page, and a dashboard per repo. vibex host adds the files to serve it from your own box, with a login that is on until you turn it off.

Build the site Serve it

$ vibex workspace ~/work --title "Relay" --host

~/work/vibex-site/index.html

dispatch 3 diagrams

scan-ingest 2 diagrams

shipment-api 4 diagrams

$ cd ~/work/vibex-site

$ VIBEX_USER=you VIBEX_PASSWORD=change-me docker compose up --build

One run from the folder above

Each top-level folder that holds specs becomes a card on the landing page and a dashboard of its own. Run it again after any spec change: new repos appear, and a repo whose specs are gone is removed from the site.

# ~/work

shipment-api/docs/arch/*.json

dispatch/architecture/*.json

scan-ingest/docs/*.json

shared/system.links.json

# becomes

vibex-site/index.html the landing page

vibex-site/shipment-api/ its dashboard

vibex-site/dispatch/ …one per repo

It skips node_modules, dist, build and folders with no specs, so it is safe to point at a folder of real checkouts.

Specs in the workspace root itself, or in a folder that is not a repo, get a card of their own. That is where cross-repo specs such as a System view usually live.

It only ever writes to a folder it built. Point -o at anything else and it stops.

This is an extra way to run it, not a new one. render and dashboard inside a single repo work exactly as before.

Where the specs live

INSIDE EACH REPO

repo-a/docs/arch/: Versioned with the code it describes. Each repo's CI runs its own vibex docs --check, and anchors are checked against that repo.

IN A SHARED FOLDER

work/shared/: One place for specs that span repos. Anchors name the repo folder, shipment-api/src/shipments.go, and are checked against the workspace. No git needed at the top: drift is a hash of the lines, and without a git history every anchor is simply re-read.

Serve it behind a login

vibex host writes plain nginx and Docker files next to any folder of pages: a workspace site, or one repo's dashboard. Nothing of vibeX runs in the container. It is nginx and your HTML, so it runs anywhere Docker does.

WHAT IT WRITES

files: Dockerfiledocker-compose.yml.dockerignore.vibex-host/
re-runs: A file vibeX wrote is refreshed. A file you wrote yourself is kept, unless you pass --force.

ENVIRONMENT

VIBEX_USER · VIBEX_PASSWORD: The login. Without both, the container refuses to start, so the docs are never served open by accident.
VIBEX_PUBLIC=1: Serve without a login, when the docs are meant to be public.
PORT: The port nginx listens on, 8080 by default. Platforms that set it, such as Railway, just work.

WHAT NGINX DOES

/healthz: Answers without the login, for a platform health check.
headers: Hosting files and dotfiles are never served. nosniff, SAMEORIGIN and no-referrer on every response.

# one repo's dashboard works the same way

$ vibex dashboard out/index.html docs --repo .

$ vibex host out

# or build and run the image yourself

$ docker build -t docs out

$ docker run -p 8080:8080 -e VIBEX_USER=you -e VIBEX_PASSWORD=change-me docs

A login, not a permission system. It is HTTP basic auth over whatever TLS sits in front of it. For per-person access, put it behind your SSO proxy and set VIBEX_PUBLIC=1.

What it connects to

DASHBOARD

One per repo

Each card on the landing page opens that repo's full dashboard: every diagram, its docs and its changes.

Dashboard →

SYSTEM VIEW

The calls between them

Keep a links spec in the shared folder and the map of who calls whom sits beside the repos it connects.

System view →

CHECKED DOCS

Drift, either way

Specs inside a repo are checked by that repo's CI. Specs in the shared folder are checked against the workspace.

Checked docs →