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:

```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.

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`.