adinhodovic/compass

What is it?

Key features

• 01Discovers services automatically from Docker, Kubernetes, Tailscale, and Headscale.
• 02Supports static config and JSON API sources.
• 03Shows source health and refresh status.
• 04Provides search, filtering, tags, and service metadata.
• 05Ships a Docker image and a Helm chart for Kubernetes.

Use cases

• Building a single dashboard for services running across several Docker hosts in a homelab.
• Listing internal Kubernetes services and their links in one place for a team.
• Browsing services exposed on a Tailscale or Headscale network from one page.

Quick start

1. 1

   Create compass.yaml with a Docker source

2. 2

   Run the Compass container with Docker

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

   For Kubernetes, create compass.yaml with a Kubernetes source

4. 4

   Install Compass with Helm

   helm install compass oci://ghcr.io/adinhodovic/charts/compass -n compass --create-namespace --set-file config=compass.yaml

Things to know

• !Docker discovery requires mounting the Docker socket, which grants sensitive host access.
• !Kubernetes discovery depends on the Helm chart's in-cluster RBAC grants.

In collections

Topics

FAQ

What is compass?

A self-hosted landing page that automatically discovers and lists your services, dashboards, and documents from Docker, Kubernetes, and Tailscale. Compass is a landing page for homelab and self-hosted setups. Instead of maintaining hand-written cards for each service, you add a source in a YAML config and Compass renders what that source exposes in a server-driven UI.

Is compass free to use? What license does it have?

compass is open source under the Apache-2.0 license. Check the license terms before using it in commercial products.

Is compass still maintained?

Actively maintained. The last commit to compass was on Nov 5, 2026.

What can I use compass for?

Building a single dashboard for services running across several Docker hosts in a homelab. Listing internal Kubernetes services and their links in one place for a team. Browsing services exposed on a Tailscale or Headscale network from one page.

How do I install compass?

Create compass.yaml with a Docker source Run the Compass container with Docker: 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 For Kubernetes, create compass.yaml with a Kubernetes source Install Compass with Helm: helm install compass oci://ghcr.io/adinhodovic/charts/compass -n compass --create-namespace --set-file config=compass.yaml

Where can I get compass?

The source code and installation instructions are on GitHub: https://github.com/adinhodovic/compass