vitrine🔗

A tiny read-only webserver for putting local source trees on display.

Point it at some directories via a small config file, and it serves them: markdown renders to HTML, directories become listings, and ?fmt=raw on any URL serves the file bytes directly. No javascript required, no uploads, no auth, no dynamic anything beyond rendering.

Config🔗

vitrine takes exactly one config file, via the required -config flag (there is no default location and no search). The format is YAML:

exhibits:
  moonshot-1:
    path: "%"
  meta/research/some-topic:
    path: ../elsewhere/some-topic
  some-repo:
    path: ../src/some-repo
    expose-git: true

• exhibits maps URL prefixes to directories. A prefix may contain slashes; the intermediate URL levels then serve synthetic listings that reveal only the mounted subtrees.
• path (required) is the directory to serve. The placeholder "%" means "same as the exhibit name" -- the common case where the URL space mirrors the directory layout. Relative paths resolve against the config file's directory, which makes a config portable alongside the trees it describes. Absolute paths also work. Trailing slashes on names and paths are accepted and normalized away.
• expose-git (optional, default false): see below.

A bad config (parse error, unknown key, missing path, or zero exhibits) is a startup error: vitrine refuses to run rather than serve the wrong thing.

Config changes apply live: vitrine watches the config file (inotify for immediate pickup, plus a 5-second stat poll as backstop, so a change lands within ~5s worst case, usually instantly). At runtime the failure mode flips from fail-loud to fail-stable: a reload that fails to parse, or names a directory that can't be opened, logs a loud REJECTED line and the previous exhibits keep serving untouched. Edit freely; a typo mid-edit can't take the server dark.

Theming🔗

Each host wears its own accent color, derived from its hostname, so when several vitrines from several hosts are open in tabs, each is recognizable at a glance. The hostname's first dot-segment (e.g. langoustine from langoustine.exe.xyz) hashes to a hue; that name is also shown next to the site name in the nav, so the color never has to carry the meaning alone.

The derivation is deterministic: the same hostname always yields the same color, on every build and every host. The -theme-seed flag substitutes any string for the hostname segment -- useful for testing, or if you dislike the color your hostname landed on.

Callouts🔗

Markdown can carry callout boxes (notes, warnings, tips, and the like) using colon fences:

:::warning  Optional title text
body content, which is **full markdown**
:::

• A line of three-or-more colons followed by a non-empty remainder opens a callout. The first word of the remainder is the callout type; anything after it is an optional title.
• A line of three-or-more colons alone closes it.
• The body is ordinary markdown: lists, emphasis, links, and code all work inside.

The rendered box is <div class="callout callout-{type}"> (matching the markdown-it-container / VuePress convention, so docs authored for those tools render as intended). The styled types are info, note, tip, success, todo, warning, danger, and reject, each with its own accent color and icon; info and note ride the per-host accent. warn is accepted as an alias for warning. An unknown type still renders as a plain neutral box.

Callouts do not nest, by design, and an unterminated callout simply runs to the end of the document rather than breaking it.

expose-git🔗

By default, .git directories are invisible: hidden from listings and unreachable by direct URL.

Setting expose-git: true on an exhibit flips that: .git lists and serves like any other directory, which makes git clone http://host/exhibit/.git work over git's dumb HTTP transport.

Two caveats, read them before enabling:

• vitrine writes into that exhibit's .git. Dumb-HTTP clone requires .git/info/refs and .git/objects/info/packs, and ordinary commits never maintain them, so vitrine runs git update-server-info on the exhibit at startup and at every successful config reload. This is a deliberate exception to vitrine's otherwise strictly read-only stance.
• Dumb HTTP has dumb semantics. Clones reflect the refs as of the last update-server-info run, so commits made after the last startup or config reload are invisible to clones until the next one (touching the config file suffices to trigger a reload). A stale clone succeeds silently at the old tip; there is no warning. Concurrent git gc in the exhibit can also break an in-flight clone (loudly; retry works).

Deployment🔗

Run vitrine as your own user, under a systemd user unit. No root anywhere.

1. Build and install the binary somewhere on your user's path:

   go build -o ~/bin/vitrine .
   

2. Write your config, e.g. ~/fusion/.vitrine.cfg, with paths relative to that directory (see Config above).

3. Install the unit file from this repo as a user unit:

   mkdir -p ~/.config/systemd/user
   cp vitrine.service ~/.config/systemd/user/
   systemctl --user daemon-reload
   systemctl --user enable --now vitrine
   

   Adjust ExecStart in the unit if your binary or config live elsewhere.

4. Keep it running after logout (user units otherwise stop with your session):

   loginctl enable-linger $USER
   

Check on it with systemctl --user status vitrine and journalctl --user -u vitrine -f.