How to Build a Personal Homelab Dashboard with Dashy in 40 Minutes

Anyone managing multiple services eventually hits a wall: Where exactly are all these entry points? Are they even running?

I used to have over 30 bookmarks scattered across my browser: Nginx, Jenkins, Grafana, various internal APIs... I had to click into each one just to check if the service was alive. Then, I spent exactly 40 minutes setting up a Dashy dashboard. Now, all services are visible at a glance, with real-time online/offline status indicators. Today, I'll break this process down into clear, step-by-step instructions so you can build your own personal dashboard in no time.

Prerequisites

• A Linux or macOS machine (Windows users will need WSL2 or Docker Desktop)
• Docker installed and running (docker --version to verify)
• No frontend development experience required. If you can edit a YAML file, you're good to go.

Why Docker? Dashy is designed for single-file configuration and single-container operation. Docker deployment is the most hassle-free approach, making updates and migrations incredibly smooth. You don't need to install Node.js or yarn locally; the container handles everything.

Step 1: Quick Start with Docker

Open your terminal and run:

docker run -d \
  -p 4000:8080 \
  -v $HOME/dashy-config:/app/user-data \
  --name dashy \
  --restart=always \
  lissy93/dashy:latest

Here's what each flag does:

• -p 4000:8080: Maps the container's port 8080 to your host's port 4000. Open http://localhost:4000 in your browser to access the dashboard. Choose any free port that doesn't conflict.
• -v $HOME/dashy-config:/app/user-data: This is critical. Mounting the configuration directory to your host ensures your settings persist. Without it, deleting the container means losing everything.
• --restart=always: Ensures the dashboard automatically restarts when your machine reboots, a must-have for Homelab environments.

After the container starts, visit http://localhost:4000. You'll see the default dashboard. Before clicking around, let's write our configuration file.

Step 2: Understanding the Configuration Structure

All Dashy configurations live in a single conf.yml file, located in the $HOME/dashy-config/ directory you just mounted.

If the directory is empty, create conf.yml and paste the following:

appConfig:
  theme: dark
  language: en-US
  statusCheck: true
  statusCheckInterval: 60

defaults:
  icon: favicon

sections:
  - name: Dev Services
    items:
      - title: Jenkins
        description: CI/CD Pipeline
        url: http://192.168.1.10:8080
        icon: https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@main/png/jenkins.png
      - title: SonarQube
        description: Code Quality Scanner
        url: http://192.168.1.10:9000
        icon: https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@main/png/sonarqube.png

Why structure it this way?

• appConfig controls global settings. theme: dark enables the dark mode. statusCheck: true automatically places a green (online) or red (offline) dot next to each service link. statusCheckInterval: 60 sets the polling frequency to 60 seconds.
• defaults.icon: favicon tells Dashy to automatically fetch the favicon from each service's URL, saving you the trouble of hunting for icons manually.
• sections are dashboard blocks. Each section acts as a card container with a name (title). Inside, items define individual links, requiring title, description, and url.

Save the file and refresh your browser (http://localhost:4000). You'll see two service cards with green status dots. This demonstrates Dashy's core strength: zero-cost service status monitoring integration.

Step 3: Integrating Widgets for Information Aggregation

Links alone aren't enough. A great dashboard should display live metrics. Dashy ships with a rich library of built-in Widgets, including weather, clocks, system info, and RSS feeds.

Append the pages configuration to your conf.yml:

pages:
  - name: Home
    displayData:
      hideHeading: true
  - name: Monitoring
    path: monitoring.yml

This enables multi-page navigation. Now, create monitoring.yml in the same configuration directory:

appConfig:
  theme: cyberpunk

sections:
  - name: System Status
    displayData:
      type: widgets
    widgets:
      - type: clock
        options:
          timezone: America/New_York
      - type: weather
        options:
          apiKey: "YOUR_OPENWEATHER_API_KEY"
          city: "New York"
      - type: glances
        options:
          hostname: http://192.168.1.10:61208

defaults:
  icon: favicon

Key highlights:

• displayData.type: widgets switches the section to widget mode.
• clock shows real-time time. Use valid IANA timezone names for timezone.
• weather requires a free OpenWeatherMap API key (register at openweathermap.org).
• glances is a powerful system monitoring combo. Glances is an open-source CLI/Web monitoring tool (pip install glances + glances -w). It exposes CPU, memory, disk, and network metrics via a Web API. Dashy's Glances Widget consumes this data directly and renders beautiful real-time charts on your dashboard.

Save the file, switch to the "Monitoring" tab in Dashy's top navigation, and you'll see your new widget panel.

Step 4: Customizing Themes and Icons

Dashy includes multiple built-in themes. Simply change appConfig.theme to dark, light, dracula, cyberpunk, one-dark, etc., save, and refresh. No CSS tweaks required.

For icons, beyond the automatic favicon fetch, Dashy supports:

• Font Awesome: e.g., fab fa-docker
• Simple Icons: e.g., si-github
• Emoji: Just use 🚀
• Local Images: Place images in public/icons/ within your config directory and reference them as icon: icons/my-service.png

Pro tip: For common self-hosted services, use the high-quality PNGs from the dashboard-icons project. CDN URLs like https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@main/png/nginx.png load fast and look professional.

Complete Production-Ready Example: Building a "Homelab Console"

You now have all the tools needed. Below is a production-grade configuration you can copy, modify, and deploy immediately.

Final directory structure:

$HOME/dashy-config/
├── conf.yml          # Main page config
└── monitoring.yml    # Monitoring sub-page config

Complete conf.yml:

appConfig:
  theme: one-dark
  language: en-US
  statusCheck: true
  statusCheckInterval: 30
  startingView: default

defaults:
  icon: favicon

sections:
  - name: Infrastructure
    items:
      - title: Proxmox
        description: Virtualization Platform
        url: https://192.168.1.100:8006
        icon: https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@main/png/proxmox.png
      - title: Router
        url: http://192.168.1.1
        icon: emoji
        iconContent: 🌐

  - name: Dev Tools
    items:
      - title: Gogs
        description: Private Git Server
        url: http://192.168.1.10:3000
        tags: [git, code]
      - title: Nexus
        description: Maven Private Registry
        url: http://192.168.1.10:8081

  - name: Quick Search
    displayData:
      type: search

Save and refresh. Your Homelab console is now live with service links, status monitoring, and quick search. Adding new services later is just a matter of appending items under the relevant sections.

FAQ & Troubleshooting Tips

1. Status indicators not showing? Ensure appConfig.statusCheck is set to true. If your services are on an isolated internal network or require authentication, the browser frontend might not reach them. In this case, add statusCheckUrl to the specific item, pointing to an accessible health-check endpoint.

2. Config changes not reflecting? Dashy applies config changes instantly, but if you edited the YAML directly via a file editor, you'll need to refresh your browser. Alternatively, use Dashy's built-in UI "Edit Mode" to modify settings directly in the browser and click "Save to Disk" to persist them.

3. Container logs throwing errors? Run docker logs dashy. The most common issues are invalid YAML syntax (use spaces, not tabs for indentation) and port conflicts. Dashy validates the config on startup and will log the exact line number for syntax errors.

4. Deploying with Docker Compose? If you manage multiple services via Docker Compose, use this configuration:

version: '3'
services:
  dashy:
    image: lissy93/dashy:latest
    ports:
      - "4000:8080"
    volumes:
      - $HOME/dashy-config:/app/user-data
    restart: always

5. Public exposure & security? If your dashboard will be accessible from the public internet, enabling authentication is strongly recommended. Add an auth block under appConfig to enable Basic Auth or Keycloak SSO, preventing unauthorized access.

Conclusion

Let's recap what we covered:

1. Deployed Dashy with a single Docker command
2. Wrote a YAML config to organize service links and enable status monitoring
3. Created a multi-page layout integrating real-time Widgets (clock, weather, system metrics)
4. Explored theme switching and icon optimization techniques

Dashy's core philosophy is "Configuration as Code: one YAML file to rule them all". Once you grasp this pattern, maintenance becomes trivial: add a line for a new service, delete a line for a retired one, and update with docker pull + docker restart.

Next steps: Try setting up hotkeys (assign numbers to hotkey fields for instant navigation), explore multi-language support, or dive into Dashy's widget ecosystem (supports RSS, Jellyfin, AdGuard Home, Home Assistant, and dozens of other self-hosted integrations).

Once your dashboard is ready, feel free to drop a screenshot. After all, building a beautiful, personalized digital workspace is one of the most rewarding parts of the self-hosting journey.