compass

module
v0.0.0-...-b2f9c62 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 5, 2026 License: Apache-2.0

README

Compass

A landing page for your services, dashboards, and documents, discovered automatically from sources such as Docker, Kubernetes, and Tailscale.

Getting started · Docs · Demo

Compass services dashboard

Why Compass

Add a source and Compass renders what is exposed in a server-driven UI with source status, tags, metadata, and operator context. Search, filter, debug, and jump into services without maintaining a pile of hand-written cards.

  • Docker, Kubernetes, Tailscale, Headscale, NetBird, static config, and JSON API sources.
  • Source health, refresh status, service metadata, panels, tags, and debug views.
  • Up/down status on service cards from Prometheus, Gatus, or any JSON endpoint you already run.
  • Server-rendered HTML with HTMX, Alpine.js, Tailwind, and daisyUI.

Quick start

Docker source compass.yaml:

organization:
  name: Homelab

services:
  sources:
    - type: docker
      name: local
# Add the host's docker GID so the non-root container user can read the socket. Alternatively use: tecnativa/docker-socket-proxy
docker run --rm -p 8080:8080 \
  --group-add $(getent group docker | cut -d: -f3) \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -v $PWD/compass.yaml:/etc/compass/compass.yaml:ro \
  adinhodovic/compass:latest \
  -c /etc/compass/compass.yaml

Kubernetes source compass.yaml:

organization:
  name: Homelab

services:
  sources:
    - type: kubernetes
      name: cluster # Helm grants in-cluster RBAC for discovery
      kubernetes:
        namespaces: []
helm install compass oci://ghcr.io/adinhodovic/charts/compass -n compass --create-namespace --set-file config=compass.yaml

See Getting started for a minimal config and source examples.

Directories

Path Synopsis
cmd
compass command
internal
metrics
Package metrics holds the Prometheus instrumentation shared by the server and registry packages.
Package metrics holds the Prometheus instrumentation shared by the server and registry packages.
pages
Package pages loads user-authored markdown files from a directory and renders them as additional Compass pages.
Package pages loads user-authored markdown files from a directory and renders them as additional Compass pages.
source/api
Package api implements the generic JSON-over-HTTP source.
Package api implements the generic JSON-over-HTTP source.
source/dnssd
Package dnssd implements Prometheus-style DNS service discovery for SRV records.
Package dnssd implements Prometheus-style DNS service discovery for SRV records.
source/netbird
Package netbird reads peers from a NetBird management server's REST API (NetBird Cloud or self-hosted) and emits a compass.Service for each peer that has an IP or DNS label.
Package netbird reads peers from a NetBird management server's REST API (NetBird Cloud or self-hosted) and emits a compass.Service for each peer that has an IP or DNS label.
source/static
Package static implements the trivial source whose services are listed directly in compass.yaml.
Package static implements the trivial source whose services are listed directly in compass.yaml.
status
Package status fetches up/down checks from an external monitoring system.
Package status fetches up/down checks from an external monitoring system.
testutil
Package testutil holds the small set of fakes that more than one test package reaches for.
Package testutil holds the small set of fakes that more than one test package reaches for.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL