How to Use Dashy: The Beginner's Guide (First Deploy, the conf.yml Rule, Status Checks, and the Widget Lesson)

CodexFuse Team · 2026-11-01T11:50:40.675Z · 13 min read

Learn how to use Dashy: the one-command Docker deploy, the conf.yml rule, server-side status checks, widgets, themes, multi-page dashboards, and auth.

What Is Dashy, Exactly?

Dashy is a free, open-source, self hosted dashboard app that turns your scattered bookmarks and IP:port addresses into one clean start page for your homelab. If you are learning how to use Dashy, the short version is: you run one Docker container, edit one YAML file (conf.yml), and every service you own — media servers, download clients, monitoring, your router — shows up as a clickable tile with a live status dot telling you whether it is up or down.

This guide is about Dashy the self-hosted dashboard (GitHub lissy93/dashy), not the Obsidian plugin or the beauty brand that share the name. The project is maintained by Alicia Sykes, carries an MIT license, and has earned over 26,000 stars — the current 4.x releases (latest published release 4.5.0, July 2026) keep the same core idea the project started with: a single config file drives everything. There is no database to back up, no Redis instance, no background workers — the docs say it plainly — and the whole dashboard loads in your browser as a fast static app served by a small Node server.

This Dashy tutorial walks the full beginner arc in one place: the one-command Docker deploy, the conf.yml rule, adding sections and items, the status-check lesson, the widget lesson, themes, multi-page dashboards, the in-browser config editor, and authentication.

Your First Dashy Setup in 10 Steps

If you want the whole arc before the detail, here it is:

1. Install Docker on the machine that will host Dashy.
2. Run the one-command Docker deploy with a /app/user-data volume mapped from your host.
3. Open http://your-server-ip:8080 and confirm the default dashboard loads.
4. Find conf.yml in your mounted user-data directory and commit it to a private git repo.
5. Edit pageInfo to name your dashboard, and set a theme in appConfig.
6. Add a section and your first three items with titles, URLs, and hl- icons.
7. Turn on status checks with statusCheckUrl and a statusCheckInterval.
8. Add one widget — a clock, weather card, or RSS feed.
9. Try the in-browser visual editor to feel the edit-preview-save loop.
10. Set up auth with the users array before the dashboard is reachable beyond your LAN.

Before You Start: What You Need

You need a machine that is already on your network and a working Docker install — any Linux box, NAS, or VPS you run your other services on will do. If you have never touched Docker, read our Docker beginner guide first; Dashy is a one-container app, so the whole deploy is a single docker run command once Docker is in place.

One thing to know before you run it: Dashy serves port 8080 inside its container (older 2.x-era guides say port 80 — that changed in 4.x, so copy-pasting an old command is the classic first-run failure). The Synology community guide tested against Dashy 4.9.0 uses the same 8080 mapping, and the official quick-start opens http://localhost:8080.

Step 1: Deploy Dashy With One Docker Command

The fastest Dashy Docker deploy is a single docker run that mounts a host directory into the container's user-data folder. Here is the current pattern:

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

Open http://your-server-ip:8080 and the default dashboard appears. Two things matter here. First, the image is also published on GHCR as ghcr.io/lissy93/dashy if you prefer it. Second, you mount a directory (/app/user-data), not the config file itself — that is a 4.x change, and old guides that mount conf.yml as a file will fight you. The directory holds your conf.yml plus any sub-page files, and because it lives on your host, your config survives container updates.

Prefer Compose? The same idea works in a docker-compose.yml with a volumes entry pointing at your user-data directory. Either way, the rule is: the container is disposable; your user-data directory is the product. The Node server idles around 80–120 MB of RAM, so 256 MB allocated is comfortable — Dashy is light enough for a Pi or a small VPS.

The conf.yml Rule: Your Config File Is the Whole Dashboard

Dashy has no database — your Dashy conf.yml is the entire Dashy dashboard. The official quick-start says the only required file is conf.yml, and the Railway deploy page confirms it needs no database, Redis instance, or background workers. Every tile, section, widget, theme, and login lives in this one YAML file, which means two habits matter more than anything else in this guide: keep a copy of the file somewhere safe, and — better still — commit it to a private git repo so every change is versioned. Deleting the container never loses your dashboard; deleting conf.yml loses everything.

The file has a simple skeleton. At the top level: pageInfo (required — the dashboard title and description), appConfig (optional — theme, auth, global status-check defaults), sections (required — where the tiles live), and pages (optional — extra dashboard pages, covered later). One 4.x strictness to respect: YAML parsing is now strict YAML 1.2, and section names must be present and unique — a duplicated section name that older versions tolerated will now break the page.

Here is the smallest useful config — everything else in this guide builds on it:

pageInfo:
  title: My Homelab
  description: Everything I run, one click away
appConfig:
  theme: colorful
sections:
  - name: Media
    items:
      - title: Jellyfin
        description: My movies and shows
        url: http://192.168.1.10:8096
        icon: hl-jellyfin
      - title: qBittorrent
        description: Downloads
        url: http://192.168.1.10:8080
        icon: hl-qbittorrent

Save the file, refresh the browser, and the tiles appear. That edit-save-refresh loop is the whole Dashy workflow — once you feel it, the rest of the guide is just adding more kinds of tiles.

Step 2: Add Sections and Items

Sections group your tiles; items are the tiles. Give each section a clear name — Media, Downloads, Monitoring, Network, Smart Home — and add an item per service. Every item needs at least a title and a url; description and icon are what make the dashboard readable at a glance.

For icons, you have three options. The easiest is the hl- prefix: Dashy integrates the homelab icon set directly, so hl-jellyfin or hl-qbittorrent just works for most popular services with no setup. That icon set is the community-maintained dashboard-icons repo — note its current home is github.com/homarr-labs/dashboard-icons (the old walkxcode/dashboard-icons path redirects there after the repo transfer), with nearly 9,000 stars and an Apache 2.0 license. For anything the set misses, point icon at any image URL — a company favicon, a PNG on your own server, whatever you like.

The Status Check Lesson: Green Dots, Checked From the Server

Each tile can show a live status dot — and here is the lesson that corrects most old guides: in current Dashy, the checks run from the Dashy server, not from your browser. The app exposes Node endpoints (/status-check/ and /ping-check/) that probe your services server-side. That means checks can reach anything the server can reach, and private-IP targets are fine as long as the server is on the same network.

Turn the Dashy status check on with fields per item:

items:
  - title: Grafana
    url: http://192.168.1.10:3000
    statusCheckUrl: http://192.168.1.10:3000/api/health
    statusCheckInterval: 5
    pingCheckEnabled: true
    pingCheckHost: 192.168.1.10

The statusCheckUrl can be a dedicated health endpoint (many services expose one, like Grafana's /api/health) or just the service URL itself; statusCheckInterval is the re-check interval in seconds; the ping fields give you a lower-level host check. You can also set global defaults once in appConfig instead of repeating them on every item. The docs list the finer knobs too: custom headers, accepted status codes, and an allow-insecure option.

Two gotchas still apply. First, if your Dashy page is served over HTTPS, the browser blocks mixed content — checking plain-HTTP endpoints from an HTTPS dashboard needs the documented insecure-allowance option. Second, some apps need an Access-Control-Allow-Origin header set on their side before Dashy can probe them cleanly. And if you would rather the server never proxy probes at all, the DISABLE_PROXY_ENDPOINTS environment variable (added in 4.5.0) turns the check endpoints off. Practical tip: if every dot shows red right after setup, test one service URL from the server with curl — if the server can reach it but the dot is red, you are looking at a headers or HTTPS issue, not a dead service.

The Widget Lesson: Make the Dashboard Inform You

Dashy widgets are the difference between a bookmark page and a dashboard: they pull live information onto the page instead of just linking to it. Dashy ships around 120 built-in widget types, configured in conf.yml with a - type: <name> entry plus an options: block per widget.

Start with the three that pay off immediately. A clock widget and a weather card make the page feel like a real start page (weather needs a free OpenWeatherMap API key in its options). The rss-feed widget turns Dashy into a morning briefing — point it at your favorite feeds, or at your own self-hosted reader; if you run one, our FreshRSS beginner guide covers the feed side. Other popular types include weather-forecast, calendar, github-stats, custom-api, and iframe.

One honest expectation: widgets show information, they do not replace the apps. An RSS widget shows headlines; you still click through to read. Dashy is a launchpad with live tiles, not a replacement for the services behind them.

Step 3: Pick a Theme

Dashy themes change the whole look with one line: appConfig.theme. Dashy ships over 40 built-in themes — and you can even set separate dayTheme and nightTheme values that follow the operating system's light/dark preference. Switching is config-only: set the key, save, refresh. No rebuild, no restart, no package install.

Try three or four before you settle. Most homelabbers pick one theme in the first week and never touch it again — which is fine, because the theme is about your morning mood, not about functionality.

Step 4: Organize With Multi-Page Dashboards

When one page fills up, Dashy lets you split the dashboard into multiple pages with the top-level pages: array. Each entry has a name and a path — either a filename inside your /app/user-data directory or a full URL — and sub-pages support their own pageInfo, sections, and appConfig, which merge with the main config. Auth and the page list itself always come from the main conf.yml, so there is one source of truth for who can log in and which pages exist.

A common split: a Home page with daily-driver tiles, a Media page, an Admin page for monitoring and infrastructure, and a Smart Home page. The beginner rule is simple: do not build five pages on day one. Run with one page until scrolling annoys you — that annoyance is the exact signal that you have outgrown a single page, and by then you will know exactly which sections belong on page two.

Step 5: Use the In-Browser Config Editor

You never have to SSH in to edit conf.yml: Dashy has a built-in visual config editor. Click the Settings/Options button in the top-right corner, choose Config, then Edit Config. There are two editors: a JSON editor for precise work, and the UI Visual Editor — an Interactive Edit Mode where you click any part of the page, edit it with a live preview, and the change is saved to disk. Release 4.5.0 even added drag-and-drop editing for rearranging tiles.

Use it freely, but remember the conf.yml rule from earlier: the editor writes back to the same conf.yml file, so your git-commit habit still applies. The editor is convenience, not a replacement for a backup.

Step 6: Lock It Down With Auth

Dashy is open to anyone who can reach the URL by default — set up auth before you expose it beyond your LAN. Current Dashy configures users in appConfig.auth.users as an array, where each entry has a user name, a hash (the SHA256 hash of the password — the docs show how to generate it), and a type such as admin:

appConfig:
  auth:
    users:
      - user: admin
        hash: 5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8
        type: admin

Do not put the plain password in the file — a plain-text password in conf.yml defeats the purpose of having auth at all. For stricter setups there is optional server-side enforcement via the ENABLE_HTTP_AUTH environment variable, plus OIDC, Keycloak, and header-based auth for teams. Note: old guides mention a passwordSha512 key — that is the 2.x-era field and is not the current pattern. Inside your own LAN, many homelabbers skip auth entirely and rely on network boundaries; the moment the dashboard is reachable from the internet, auth is non-negotiable.

Dashy vs the Alternatives: A Quick Draw-the-Line

Dashy is one of several self-hosted dashboards, and the differences are about what you value. Heimdall is the simpler, prettier bookmark page — easier, but its tiles are mostly static links. Homer is the minimalist's YAML dashboard — fast and clean, but with fewer built-in widgets. Dashy sits in the middle: richer than Homer, more flexible than Heimdall, with real server-side status checks and over a hundred widgets, at the cost of a slightly bigger config file.

The honest comparison table:

Pick Dashy when you want the status dots and widgets; pick Heimdall or Homer when you want the simplest possible start page. None of them is wrong — they are different answers to "too many bookmarks."

7 Beginner Mistakes to Avoid

What to Run Next to Dashy

Dashy shows your services; it does not manage them. The natural companion is a container GUI: our Portainer beginner guide covers the point-and-click way to manage the same Docker containers your Dashy tiles link to. And if you want the machine underneath to be solid, our what is VPS hosting guide explains the server side.

Frequently Asked Questions

Is Dashy free?

Yes. Dashy is open source under the MIT license and free to self-host — the only cost is whatever machine you run it on, which for most homelabbers is hardware they already own.

Does Dashy need a database?

No. Dashy has no database at all — conf.yml is the entire dashboard, with no Redis instance or background workers required. Back up that one file (or commit it to git) and you can rebuild everything in minutes.

Why do my status checks show red when the service is up?

Status checks probe from the Dashy server, not your browser. Curl the same URL from the server first — if the server reaches it but the dot is red, you are almost always looking at a headers issue (the app needs an Access-Control-Allow-Origin header) or mixed content (an HTTP service behind an HTTPS Dashy page), not a dead service.

Can I edit the dashboard without SSH?

Yes. Dashy ships a built-in visual config editor — Settings/Options, top-right, then Config, then Edit Config — with an Interactive Edit Mode that previews changes live and saves them to disk.

Dashy vs Heimdall — which should I pick?

Pick Dashy if you want server-side status checks and a hundred-plus widgets; pick Heimdall if you want the simplest possible pretty bookmark page. They solve the same "too many bookmarks" problem with different trade-offs.

Sources

All facts verified at write time, 2026-11-01: GitHub API for lissy93/dashy (release 4.5.0 published 2026-07-26, newest tag 4.9.12, 26,884 stars, 1,964 forks, MIT license) and homarr-labs/dashboard-icons (8,982 stars, Apache 2.0 — the walkxcode/dashboard-icons path now redirects there); Dashy 4.0.0 release notes (Vue 3 / Node 24 rewrite, non-root image, directory mounts, strict YAML 1.2); the official Dashy docs — quick-start (one-command Docker deploy, internal port 8080, /app/user-data volume, conf.yml as the only required file), configuring (top-level keys pageInfo/appConfig/sections/pages, item fields, Interactive Edit Mode config editor), status-indicators (server-side Node endpoints /status-check/ and /ping-check/, statusCheckUrl/statusCheckInterval, ping fields, accepted codes and headers), widgets (- type: plus options: pattern, ~120 built-in types, OpenWeatherMap apiKey for weather), theming (appConfig.theme, 40+ themes, dayTheme/nightTheme), pages-and-sections (pages: array with name and path), authentication (appConfig.auth.users with SHA256 hash, ENABLE_HTTP_AUTH, OIDC/Keycloak/HeaderAuth), and deployment (idle RAM ~80–120 MB, GHCR image); the Railway Dashy deploy page (no database, Redis, or background workers; editor path via Settings/Options); the usavps.com Dashy-on-VPS guide (October 6, 2026) and the mariushosting.com Synology guide (tested with Dashy 4.9.0) for the intent landscape.