# cairn

> Guest-first, multilingual directory page for self-hosted services. One Go
> binary (FROM scratch, ~10 MB, 4.3 MB to pull) renders YAML config into a
> server-side page with live Gatus status pills, search, light/dark, and
> hosted legal pages. No database, no tracking, no runtime dependencies.

Key facts: config lives in `/config/*.yaml` (site.yaml for the site, any
other yaml lists services), reloads live within ~2 s, config errors name the
file and line, unknown keys are errors. Everything user-visible is
translatable per-locale inline. Image: ghcr.io/morgankryze/cairn
(latest/stable = releases, unstable = main). Live instance:
https://cairn.libresoftware.cloud

## Docs

- [Getting started](docs/getting-started.md): zero to a served page in five minutes
- [Upgrading](docs/upgrading.md): the dry run before you switch, and every config shape a version has started refusing, each with its verbatim error and its fix
- [Services](docs/configuration/services.md): the cards; every key with defaults
- [Site](docs/configuration/site.md): title, welcome note, header links, hosted legal pages, footer, credit
- [Writing text](docs/configuration/text.md): the long fields take CommonMark plus GFM, minus raw HTML, with a link-scheme allow-list and whole-block images as figures
- [Theming](docs/configuration/theming.md): accent, light/dark toggle, custom.css variables
- [Languages](docs/configuration/i18n.md): locale negotiation, translatable fields, UI strings
- [Docker Compose](docs/deployment/docker-compose.md): hardened reference setup and image tags
- [Podman](docs/deployment/podman.md): the same container as a rootless systemd quadlet
- [Bare binary](docs/deployment/binary.md): no container, flags and a hardened systemd unit
- [Kubernetes](docs/deployment/kubernetes.md): ConfigMap, Deployment, Service, why the two probes differ
- [Helm](docs/deployment/helm.md): chart at oci://ghcr.io/morgankryze/charts/cairn, config in values, Ingress
- [Air-gapped](docs/deployment/airgap.md): offline install with and without a registry, -emit-icons, -check with both mounts
- [Static hosting](docs/deployment/static.md): -export to a directory, zip or tar; what a static site gives up (status pills); Cloudflare Pages, Netlify, Apache/OVH; a CI pipeline
- [Reverse proxies](docs/deployment/reverse-proxies.md): Caddy, Traefik, Nginx examples
- [Status with Gatus](docs/recipes/gatus.md): -emit-gatus, polling, pill behavior
- [Icons](docs/recipes/icons.md): slugs, URLs, self-hosted files
- [Multiple files](docs/recipes/multiple-files.md): one YAML per category
- [Migration](docs/recipes/migration.md): mapping a Homer or Homepage config over, field by field
- [Reference](docs/reference.md): every key, flag and endpoint on one page
- [FAQ](docs/faq.md): tracking, cookies, JavaScript, auth
- [Comparison](docs/comparison.md): when Homer or Homepage fit better

## Source

- [src/](src/): six packages under src/internal (config, render, status,
  server, check, testutil) plus src/cmd/cairn for wiring; render/templates and
  render/assets are embedded into the binary
- [demo/](demo/README.md): compose stack with cairn, Gatus and sample services
- [CONTRIBUTING.md](CONTRIBUTING.md): dev loop, scope rules, commit style