Linkus

Linkus is a configurable homepage dashboard for self-hosters who run it behind an external authentication proxy such as Traefik with Authelia. It provides a central hub for services, HTTP status checks, critical alerts, and small dashboard plugins.

The main feature is group-aware visibility: Linkus reads trusted proxy headers and shows only the services and plugins the current user may access.

Linkus is implemented as a Go application using net/http, chi, html/template, embedded static assets, PicoCSS, and a Dracula-inspired theme.

Features

• Dynamic visibility: Shows services, plugins, and critical alerts based on user and group mappings from trusted proxy headers.
• Service modules: Displays configured links and HTTP checks with response status and response time.
• Icons: Supports Lucide icon names or direct icon URLs in the icon field.
• Plugins: Includes clock, sabnzbd, and arrCalendar widgets.
• Critical alerts: Supports ping, JSON response, and text response checks.
• Config-driven: Services, categories, plugins, users, groups, and alert checks are configured in YAML.
• Theming: Uses PicoCSS plus web/static/css/dracula.css and app-specific CSS.

Security Model

Linkus expects to run behind a trusted reverse proxy such as Traefik with Authelia. The proxy must authenticate users, set Remote-User, Remote-Name, Remote-Groups, and Remote-Email, strip any client-supplied versions of those headers, and prevent direct public access to the Linkus container or process.

Do not expose Linkus directly to untrusted clients unless you add another trusted-header boundary in front of it.

Running With Docker Compose

Use the included docker-compose.yml:

docker compose up -d

Linkus listens on http://localhost:3000 by default. Mount or create config/config.yaml based on config.example.yaml, then restart the container after changing configuration:

docker compose restart linkus

Local Development

Prerequisites:

• just
• Docker
• devcontainer CLI

Common commands:

just setup
just run
just test
just check
just build

Configuration

All application settings are managed in config/config.yaml. See config.example.yaml for the complete schema and examples.

Architecture

See DESIGN.md for implementation details.

Contributing

See CONTRIBUTING.md for development workflow and plugin guidance.

---

Note: This project was developed with AI assistance.