DOCSEARCHbyAlgolia
Submit Docs

Dashy Dashboard

repository·master·Indexed 12 days ago

https://github.com/lissy93/dashy

A highly customizable, self-hosted dashboard for homelabs featuring real-time status monitoring, widgets, multi-page support, and extensive theming. Version 4.5.8 supports deployment via Docker, bare metal (Node 20+), or static cloud hosting. It includes a REST API, built-in basic authentication, and a YAML-based configuration system with an interactive UI editor.

Tokens
106.9K
Snippets
334
Records
479
Agent score
97%

What's inside Dashy

  1. Overview of Dashy Deployment Methods

    master

    Dashy can be deployed using several different strategies depending on your infrastructure:

    • Docker: Recommended for self-hosting. Supports docker run, docker-compose, and Podman.
    • Bare Metal: Deploying via source build or pre-built releases.
    • Self-Hosted Operating Systems: Specialized support for TrueNAS SCALE, Proxmox VE, Unraid, Synology NAS, NixOS, and Kubernetes.
    • Self-Hosted Platforms: Managed platforms like Portainer, Coolify, 1Panel, Runtipi, Cosmos Cloud, CasaOS, Umbrel, EasyPanel, and Saltbox.
    • Cloud Services:
      • Static Hosting: Netlify, Vercel, EdgeOne Pages, Cloudflare Pages, Firebase Hosting, Azure Static Web Apps.
      • Container Runtimes: Render, Railway, Fly.io, Koyeb, Northflank, DigitalOcean App Platform, Azure Container Apps, Google Cloud Run.
      • Managed Hosting & CDNs: Any CDN or managed hosting provider.

  2. Overview of Dashy Widgets

    master

    Dashy supports displaying dynamic content through widgets. These are categorized into several types:

    • General Widgets: Built-in widgets for common services like Weather, RSS feeds, Crypto, and GitHub stats.
    • Self-Hosted Services Widgets: Specialized widgets designed to pull data from common self-hosted tools like Pi-Hole, Nextcloud, Proxmox, and Uptime Kuma.
    • System Resource Monitoring: Widgets for tracking hardware performance such as CPU usage, Memory, Disk IO, and Network traffic.
    • Dynamic Widgets: Advanced widgets that allow you to embed external content via Iframes, HTML, API responses, Prometheus data, or generic Data Feeds.

    Widgets can be configured to provide real-time updates and can be customized using CSS or specific UI options.

  3. Explore Dashy features

    master

    Dashy provides several advanced features for customizing your dashboard experience:

    • Authentication: Protect your dashboard with authentication.
    • Pages and Sections: Organize your dashboard using multi-page support, sections, items, and sub-items.
    • Widgets: Add dynamic content to your dashboard using various widgets.
    • Theming: Apply, write, and modify custom themes and styles.
    • Status Indicators: Monitor the uptime and status of your apps, services, or hosts.
    • REST API: Programmatically read and update your configuration over HTTP.
    • Icons: Use various icon types for sections and items.
    • Backup & Restore: Use Dashy's cloud sync feature to back up your configuration.
    • Searching & Shortcuts: Use searching and keyboard shortcuts to launch items.

  4. How to contribute to Dashy

    master

    There are several ways to contribute to the Dashy project:

    • Code & Docs: Fix bugs, add features, or improve documentation via Pull Requests. Refer to the Development Docs for environment setup.
    • Translations: Add support for new languages by translating locale files.
    • Bug Reports: Raise issues on GitHub when you find a bug. Include environment details, reproduction steps, and console output.
    • Community: Join the GitHub Discussions to share tips, ask questions, or offer support.
    • Feature Requests: Use BountySource to sponsor the development of specific features you want to see implemented.

  5. Understand Dashy's Privacy Model

    master

    Dashy is designed with a privacy-first approach for self-hosting. Its core privacy principles are:

    • No unsolicited external requests: No data is sent to external servers unless you explicitly enable a feature that requires it.
    • Open Source: The codebase is 100% open source and auditable.
    • No Tracking: There are no premium features, analytics, tracking, or advertisements.
    • Local-First: Most user preferences and authentication tokens are stored locally in your browser rather than on a central server.

  6. How Dashy's Keycloak implementation works

    master

    Dashy uses an OIDC (OpenID Connect) pipeline for both Keycloak and generic OIDC providers. For Keycloak specifically, Dashy uses a Single Page Application (SPA) adapter via keycloak-js to support check-sso and silent token renewal.

    Client-side Flow

    1. Initialization: After fetching and parsing /conf.yml, Dashy checks if Keycloak is enabled. If so, it initializes the Keycloak client with { onLoad: 'check-sso', responseMode: 'query' }.
    2. Authentication: If a session exists, the user is silently authenticated. Otherwise, the SPA redirects to the Keycloak login page using PKCE.
    3. Persistence: Upon successful return, Dashy stores the id_token, user groups, roles, preferred_username, and a derived isAdmin flag in localStorage.
    4. API Calls: Every internal API call includes an Authorization: Bearer <id_token> header. The client performs a local exp (expiry) check before sending the request to prevent unnecessary 401 errors.

    Server-side Flow

    1. Middleware: Dashy uses a Connect middleware that verifies the Bearer token against the realm's JWKS (JSON Web Key Set).
    2. Verification: The server validates the token's signature, issuer, audience (must match clientId), and expiry (with a 30-second clock-skew tolerance).
    3. Admin Derivation: The isAdmin status is derived by checking if the token's groups claim matches the configured adminGroup, or if the union of realm_access.roles and resource_access.<clientId>.roles matches the adminRole.
    4. Config Protection:
      • GET /conf.yml: If unauthenticated, the server returns a "stripped" configuration containing only the auth block and minimal pageInfo. If authenticated, the full configuration is served.
      • POST /config-manager/save: This route is guarded by requireAdmin. It returns 401 if the user is unauthenticated and 403 if the user is authenticated but not an admin.

  7. How theme-switching works in Dashy

    master

    Dashy manages themes by changing the data-theme attribute on the root DOM element. All styling is driven by CSS variables.

    When a theme is selected, Dashy applies any CSS defined within the selector html[data-theme='your-theme-name'] {}.

    To set a default theme, use appConfig.theme. You can also use dayTheme and nightTheme to automatically adjust the theme based on the user's OS light/dark mode preferences.

  8. Understand the security model for external authentication methods

    master

    Most authentication methods described in Dashy (Reverse Proxy, Zero-Trust Tunnels, VPN, IP-based access, Web Server Auth, mTLS, SSO, and Cloud Hosting) authenticate at the network or proxy edge, not inside Dashy itself.

    Critical Security Requirement: Because Dashy's own server remains open to anything that can reach it directly, you must not expose Dashy's port publicly. Instead, bind Dashy to localhost or an internal network and only allow your proxy or tunnel to communicate with it.

    If you require application-level authentication with per-user roles, you should use OIDC, built-in auth, or header auth instead.

  9. Switch between Alternate Views

    master

    Dashy provides different layout modes:

    • Default view: The standard homepage.
    • Minimal view: A simplified layout suitable for use as a browser start page.
    • Workspace view: A layout designed for visiting many apps simultaneously.

    To change the view:

    1. Use the switch icon in the top-right corner of the UI.
    2. Set a default view in your configuration using appConfig.startingView.

  10. Verify Dashy Releases and Supply Chain

    master

    Dashy provides several mechanisms to ensure the integrity and provenance of its software:

    • Verifiable Releases: Every release is built via GitHub Actions and includes a signed provenance attestation (tied to GitHub's OIDC identity). You can verify downloads using the GitHub CLI: gh attestation verify.
    • Software Bill of Materials (SBOM): Each build publishes an SBOM, providing a full manifest of all included packages.
    • Docker Security: Official Docker images are built using multi-stage builds, run as a non-root user by default, use a minimal Alpine base, and are scanned with Trivy for vulnerabilities before publishing.

  11. Choose a Protection Mode for Built-In Auth

    master

    Dashy offers three modes of protection depending on whether you want client-side UI gating or server-side enforcement:

    1. Client-side only: Set auth.users in conf.yml. Shows a login screen, but unauthenticated users can still access API endpoints if they know the URLs. Suitable for trusted LAN environments.
    2. Server-enforced via conf.yml users: Set auth.users in conf.yml AND set ENABLE_HTTP_AUTH=true. This is the recommended setup. Every API request requires a valid session token.
    3. Static credentials: Skip auth.users and set BASIC_AUTH_USERNAME and BASIC_AUTH_PASSWORD environment variables. This uses native browser HTTP Basic Auth. Best for single-user or machine-to-machine setups. Do not combine this with auth.users.
    # For Server-enforced via conf.yml users
ENABLE_HTTP_AUTH=true

# OR for Static credentials
BASIC_AUTH_USERNAME=alicia
BASIC_AUTH_PASSWORD=supersecret

  12. Understand Server-Side OIDC Enforcement

    master

    Dashy performs server-side verification of OIDC tokens to protect the API and configuration.

    Enforcement Mechanism:

    1. Dashy fetches the OIDC discovery doc and JWKS from your endpoint at boot.
    2. The SPA attaches the id_token to every API call as Authorization: Bearer <id_token>.
    3. The server verifies the token's signature, issuer, audience, and expiry.
    4. Write Protection: Endpoints like POST /config-manager/save require the adminGroup or adminRole claim to be present in the token.
    5. Data Protection: Unauthenticated requests for /conf.yml receive a stripped response containing only minimal auth and pageInfo data.

    Opting Out (Not Recommended): You can set disableServerSideCheck: true to make authentication purely client-side. This should only be used in trusted environments or when your provider does not support server-side verification.