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:
  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 (optional) is the directory to serve. When omitted, it defaults to the exhibit's own 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, 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.

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.