How to Self-Host Dashy with Docker Compose

What Is Dashy?

Dashy is a self-hosted dashboard application for organizing and monitoring your home server services. It stands out from other dashboards with 25+ built-in themes, a visual config editor in the web UI, real-time status checks for every service, 50+ widgets for displaying dynamic data, multi-page support, and Keycloak/OIDC authentication. Dashy is built with Vue.js and runs as a Node.js application behind the scenes. It replaces browser bookmark pages, Notion dashboards, or any ad-hoc system you use to keep track of your self-hosted apps.

Prerequisites

A Linux server (Ubuntu 22.04+ recommended)
Docker and Docker Compose installed (guide)
512 MB of free RAM
500 MB of free disk space
A domain name (optional, for remote access)

Docker Compose Configuration

Create a directory for Dashy and a starter configuration file:

mkdir -p ~/dashy/user-data

Create ~/dashy/user-data/conf.yml with a minimal starting config:

pageInfo:
  title: My Dashboard
  description: Self-hosted service dashboard
  navLinks:
    - title: GitHub
      path: https://github.com
    - title: Dashy Docs
      path: https://dashy.to/docs

appConfig:
  theme: colorful
  statusCheck: true
  statusCheckInterval: 60
  layout: auto
  iconSize: medium
  language: en

sections:
  - name: Services
    icon: fas fa-server
    items:
      - title: Router
        url: http://192.168.1.1
        icon: fas fa-wifi
      - title: Portainer
        url: http://your-server-ip:9000
        icon: hl-portainer

Now create docker-compose.yml:

services:
  dashy:
    image: lissy93/dashy:3.1.1
    container_name: dashy
    restart: unless-stopped
    ports:
      - "4000:8080"
    environment:
      NODE_ENV: production           # Run in production mode (faster, no dev tooling)
      # UID: 1000                    # Optional: run as a specific user ID
      # GID: 1000                    # Optional: run as a specific group ID
    volumes:
      - ./user-data/conf.yml:/app/user-data/conf.yml  # Dashboard configuration
      - ./user-data/item-icons:/app/user-data/item-icons  # Custom icons directory
    healthcheck:
      test: ['CMD', 'node', '/app/services/healthcheck']
      interval: 1m30s
      timeout: 10s
      retries: 3
      start_period: 40s

Start the stack:

cd ~/dashy && docker compose up -d

Dashy takes 30-60 seconds on first launch to build its assets. Watch the logs:

docker compose logs -f dashy

Once you see the server is running, open http://your-server-ip:4000 in your browser.

Initial Setup

Open http://your-server-ip:4000 in your browser
You should see the dashboard with the sections you defined in conf.yml
Click the pencil icon in the top-right to open the visual config editor
Add your services by editing sections and items directly in the UI
Click Save to write changes back to conf.yml

Dashy supports three editing methods:

Visual editor — click the pencil icon, then click any element on the page to edit it inline
JSON/YAML editor — open the config menu for a raw editor with built-in validation
Direct file editing — edit conf.yml on disk and restart the container

The visual editor is the fastest way to get started. For reproducible setups, managing conf.yml directly is better.

Configuration

Dashy’s entire configuration lives in a single conf.yml file. The file has four top-level sections:

pageInfo (Required)

Controls the dashboard header, title, navigation links, and footer:

pageInfo:
  title: My Homelab
  description: Service dashboard
  logo: /item-icons/logo.png        # Custom logo (place in item-icons volume)
  navLinks:
    - title: GitHub
      path: https://github.com
  footerText: ""                     # Optional footer text

appConfig (Optional)

Controls application behavior, theme, authentication, and features:

appConfig:
  theme: dracula                     # Built-in theme name
  statusCheck: true                  # Enable status indicators for all items
  statusCheckInterval: 30            # Check every 30 seconds
  layout: auto                       # auto, horizontal, vertical, or sidebar
  iconSize: medium                   # small, medium, or large
  language: en                       # UI language
  startingView: default              # default, minimal, or workspace
  defaultOpeningMethod: newtab       # newtab, sametab, modal, or workspace
  webSearch:
    searchEngine: duckduckgo         # Search engine for the search bar
    openingMethod: newtab
  hideComponents:
    hideHeading: false
    hideSearch: false
    hideSettings: false
    hideFooter: false

sections (Required)

Sections group your services. Each section contains items (links to services) and optionally widgets:

sections:
  - name: Media
    icon: fas fa-film
    displayData:
      sortBy: default
      collapsed: false
      cols: 2                        # Number of columns for items
    items:
      - title: Jellyfin
        url: https://jellyfin.example.com
        icon: hl-jellyfin
        description: Media server
        target: newtab
        statusCheck: true
        tags:
          - media
          - streaming
      - title: Navidrome
        url: https://navidrome.example.com
        icon: hl-navidrome
        description: Music server

  - name: System Monitoring
    icon: fas fa-chart-line
    widgets:
      - type: gl-current-cpu
      - type: gl-current-memory
      - type: gl-disk-space

pages (Optional)

For multi-page dashboards, define additional config files:

pages:
  - name: Networking
    path: networking.yml
  - name: Media
    path: media.yml

Place the additional YAML files in the same user-data directory.

Icon Options

Dashy supports multiple icon sources:

Homelab Icons — prefix with hl- (e.g., hl-jellyfin, hl-portainer)
Font Awesome — prefix with fas fa-, fab fa-, etc.
Material Design Icons — prefix with mdi-
Emoji — use directly (e.g., 🎬)
Favicon — set icon: favicon to auto-fetch the service’s favicon
URL — point to any image URL
Local file — place in the item-icons volume and reference by filename

Advanced Configuration

Status Checks

Status indicators show whether each service is online. Enable globally or per-item:

# Global: all items get status checks
appConfig:
  statusCheck: true
  statusCheckInterval: 30           # Seconds between checks

# Per-item: override for specific services
items:
  - title: Internal API
    url: https://api.internal.example.com
    statusCheck: true
    statusCheckUrl: https://api.internal.example.com/health  # Custom health endpoint
    statusCheckHeaders:
      Authorization: Bearer your-token-here                  # Auth headers if needed
    statusCheckAllowInsecure: true                           # Allow self-signed certs
    statusCheckAcceptCodes: "200,301,403"                    # Accept non-200 as "up"

Status indicators display as colored dots: green (online), red (offline), yellow (loading), grey (unreachable).

Widgets

Dashy includes 50+ widgets for displaying dynamic content. Add them to any section:

sections:
  - name: Widgets
    widgets:
      - type: clock
        options:
          timeZone: America/New_York
          format: en-US
      - type: weather
        options:
          apiKey: your-openweathermap-key
          city: New York
          units: imperial
      - type: pi-hole-stats
        options:
          hostname: http://pihole:80
      - type: github-profile-stats
        options:
          username: your-github-username

Widget categories include:

General — clock, weather, crypto prices, news feeds, XKCD comics
Self-hosted services — Pi-hole stats, AdGuard Home, Nextcloud, Proxmox
System monitoring — CPU, memory, disk, network usage (requires Glances)

System monitoring widgets require Glances running on the host. Add it to your Compose file:

  glances:
    image: nicolargo/glances:4.5.2-full
    container_name: glances
    restart: unless-stopped
    pid: host
    privileged: true
    ports:
      - "61208:61208"
    environment:
      GLANCES_OPT: "-w"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro

Then point Dashy’s system widgets at http://glances:61208.

Custom Themes

Beyond the 25+ built-in themes, create your own:

appConfig:
  theme: my-custom-theme
  cssThemes:
    - my-custom-theme

Then add a custom.css file or use the Custom Styles tab in the config menu:

html[data-theme='my-custom-theme'] {
  --primary: #6366f1;
  --background: #0f172a;
  --background-darker: #020617;
  --surface: #1e293b;
  --curve-factor: 10px;
  --font-body: 'Inter', sans-serif;
}

You can also load external stylesheets:

appConfig:
  externalStyleSheet:
    - https://example.com/my-dashy-theme.css

Authentication

Dashy supports several authentication methods. Built-in auth is suitable for private networks but should not be relied on for public-facing instances.

Built-in users:

appConfig:
  auth:
    users:
      - user: admin
        hash: "5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8"  # SHA-256 of 'password' — CHANGE THIS
        type: admin
      - user: viewer
        hash: "your-sha256-hash-here"
        type: normal
    enableGuestAccess: true          # Allow read-only access without login

Generate a password hash:

echo -n 'your-password' | sha256sum | awk '{print $1}'

Keycloak SSO:

appConfig:
  auth:
    enableKeycloak: true
    keycloak:
      serverUrl: https://keycloak.example.com
      realm: homelab
      clientId: dashy

OIDC (Authentik, Authelia, etc.):

appConfig:
  auth:
    enableOidc: true
    oidc:
      clientId: dashy
      endpoint: https://auth.example.com/application/o/dashy

For public-facing deployments, use Keycloak, OIDC, or reverse proxy authentication (Authelia, Authentik) instead of Dashy’s built-in auth. See How to Self-Host Authelia for a reverse proxy auth setup.

HTTP Basic Auth for Config Protection

Protect the configuration endpoint with environment variables:

environment:
  NODE_ENV: production
  BASIC_AUTH_USERNAME: admin
  BASIC_AUTH_PASSWORD: your-secure-password

This adds HTTP Basic Auth to Dashy’s config file endpoints, preventing unauthorized config changes.

Reverse Proxy

Nginx Proxy Manager config:

Scheme: http
Forward Hostname: dashy
Forward Port: 8080
Enable WebSocket Support: Yes

Caddy example:

dashy.example.com {
    reverse_proxy dashy:8080
}

Traefik labels:

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.dashy.rule=Host(`dashy.example.com`)"
  - "traefik.http.routers.dashy.entrypoints=websecure"
  - "traefik.http.routers.dashy.tls.certresolver=letsencrypt"
  - "traefik.http.services.dashy.loadbalancer.server.port=8080"

See Reverse Proxy Setup for full configuration.

Backup

Dashy stores all configuration in the conf.yml file and custom icons in the item-icons directory. Back up the entire user-data directory:

tar czf dashy-backup-$(date +%Y%m%d).tar.gz -C ~/dashy user-data/

To restore:

tar xzf dashy-backup-20260224.tar.gz -C ~/dashy
docker compose restart dashy

Dashy also supports encrypted cloud backup and restore through the UI (Settings > Cloud Backup). This uploads your config to an encrypted endpoint that you can restore from on any instance.

See Backup Strategy for a complete backup approach.

Troubleshooting

Dashboard Shows Blank Page After Start

Symptom: Browser loads but shows a white page or spinner that never resolves. Fix: Dashy takes 30-60 seconds to build assets on first launch. Check docker compose logs dashy for progress. If it persists, verify NODE_ENV is set to production — development mode is significantly slower. Also confirm your conf.yml is valid YAML with no syntax errors by running python3 -c "import yaml; yaml.safe_load(open('user-data/conf.yml'))".

Status Checks All Show Grey or Red

Symptom: Status indicators never turn green, even for services that are running. Fix: Status checks run server-side from inside the Dashy container. The container must be able to reach your services. If services are on the same Docker network, use container names (e.g., http://jellyfin:8096) instead of localhost. For services on the host, use http://host.docker.internal:port or the host’s LAN IP. If services use self-signed certificates, set statusCheckAllowInsecure: true on the item.

Config Changes Not Saving From the UI

Symptom: You edit the dashboard in the visual editor, click Save, but changes revert on refresh. Fix: Verify the volume mount gives write access. The container writes to /app/user-data/conf.yml. Check file permissions: ls -la ~/dashy/user-data/conf.yml. The file must be writable by the container’s user (UID 1000 by default, or the UID you set in the environment). Fix with chmod 666 ~/dashy/user-data/conf.yml or set matching UID/GID environment variables.

Container Fails Health Check and Restarts

Symptom: Container keeps restarting. docker compose ps shows (health: starting) or (unhealthy). Fix: Dashy’s initial build can exceed the default health check timing. Increase start_period in the health check to 60s or 90s. If the issue persists after initial startup, check logs for JavaScript errors or memory issues. Increase available memory if the container is being OOM-killed.

Custom Icons Not Loading

Symptom: Icons placed in the item-icons directory show as broken images. Fix: Verify the volume mount path is correct: ./user-data/item-icons:/app/user-data/item-icons. Reference icons in your config as just the filename (e.g., icon: my-icon.png), not a full path. Supported formats are PNG, SVG, and JPG. After adding icons, restart the container: docker compose restart dashy.

Resource Requirements

RAM: ~200-400 MB (depends on number of widgets and status checks active)
CPU: Low-medium. Initial build is CPU-intensive for 30-60 seconds. After that, periodic spikes from status checks and widget updates.
Disk: ~300 MB for the application, plus your configuration and custom icons

Dashy uses noticeably more resources than lighter dashboards like Homepage or Heimdall. The trade-off is significantly more features.

Dashboard Comparison

Feature	Dashy	Homarr	Homepage
Configuration	YAML file + visual UI editor	Web UI (drag-and-drop)	YAML files only
Built-in themes	25+	5+	None (CSS customization)
Status checks	Built-in, per-item	Built-in via Docker	Built-in via widgets
Widgets	50+ types	15+ types	20+ service widgets
Authentication	Built-in, Keycloak, OIDC	Built-in, LDAP, OIDC	None (proxy auth)
Multi-page	Yes	Yes (boards)	Yes (tabs)
Docker integration	No	Deep (start/stop containers)	Read-only status
Custom icons	Multiple sources	Built-in library	Material icons + URLs
Search	Built-in with hotkeys	Built-in	Built-in
Resource usage	Medium-high (~300 MB)	Low-medium (~150 MB)	Low (~80 MB)
Setup complexity	Low-medium	Low	Medium (YAML only)

Verdict

Dashy is the most feature-rich self-hosted dashboard available. If you want maximum customization — dozens of themes, extensive widget support, status monitoring, multi-page dashboards, and SSO — Dashy delivers all of it. The visual config editor makes it approachable despite the depth of options.

The trade-off is resource usage. Dashy runs a full Node.js server and consumes 2-4x the RAM of Homepage, which achieves similar service integration with a lighter footprint but requires YAML-only configuration. Homarr sits in the middle — its drag-and-drop UI is more polished than Dashy’s visual editor, and its Docker integration (start/stop containers from the dashboard) is genuinely useful, but it has fewer themes and widgets.

Pick Dashy if you want the most configurable dashboard with the widest widget selection and you do not mind the extra resource overhead. Pick Homarr if you value a polished UI and Docker container management. Pick Homepage if you want the lightest, fastest dashboard and are comfortable editing YAML files.

For most homelab users who want a balance of features and simplicity, Homarr is the easier starting point. But if you are the kind of person who customizes everything, Dashy will reward the effort.

Frequently Asked Questions

Is Dashy still maintained?

Yes. Dashy is actively maintained on GitHub with regular releases. The project is open-source under the MIT license. Check the GitHub repository for the latest release and commit activity.

How does Dashy compare to Homarr and Homepage?

Dashy has the most features: 25+ themes, 50+ widgets, visual config editor, multi-page dashboards, and SSO. Homarr has a more polished drag-and-drop UI and better Docker integration (start/stop containers), but fewer themes and widgets. Homepage is the lightest option (~80 MB RAM) with good service integration, but requires YAML-only configuration. See the comparison table in the Dashboard Comparison section above.

Can I edit Dashy’s config through the web UI?

Yes. Dashy offers three editing methods: a visual editor (click the pencil icon to edit elements inline), a JSON/YAML editor (for raw configuration editing), and direct file editing on disk. Changes made through the web UI are saved to conf.yml automatically. For reproducible setups, managing conf.yml directly in version control is recommended.

Does Dashy support status monitoring?

Yes. Enable statusCheck: true in appConfig to add status indicators to all services. Each item shows a colored dot — green (online), red (offline), yellow (loading), grey (unreachable). You can customize the health endpoint, accepted status codes, and authentication headers per service. Status checks run server-side from inside the Dashy container.

Why does Dashy take so long to start?

Dashy builds its frontend assets on first launch, which takes 30-60 seconds. Set NODE_ENV: production in your Docker Compose file to speed this up. Subsequent starts after the first build are faster. If startup consistently takes over 2 minutes, check available RAM — Dashy needs at least 512 MB to build assets without issues.

Can I use Dashy with Keycloak or OIDC?

Yes. Dashy supports Keycloak SSO and OIDC authentication natively. Configure it in appConfig.auth in your conf.yml. For public-facing deployments, use Keycloak, OIDC, or reverse proxy authentication (Authelia, Authentik) instead of Dashy’s built-in username/password auth, which is designed for private networks only.