A simplistic, centralized & dynamic dashboard application for your container based home network.

Posted by Martijn on Sat, Jun 10, 2023


HomeDash is a simplistic, centralized & dynamic dashboard application for your container based home network. It provides a REST API endpoint that allows you to add applications to the dashboard.

Features include:

  • Single, statically compiled binary
  • Basic UI for dashboard based on plain HTML, CSS and a sprinkling of VueJS
  • Automated, regular removal/refresh of entries older that X minutes
  • Configuration through environment variables or config.yml file
  • Swagger docs for REST API (see http://localhost:8080/static/docs)
  • Distroless container image
  • Multi-architecture container image

Keep in mind that dashboard is intended for local usage, so there are no provisions for authentication, etc.

Why create HomeDash?

So why did I create this when there are already so many dashboard applications out there?

I looked around a fair bit, tried several different dashboards but found that a lot of them implemented only part of what I wanted.

Another problem I came across was bloat. I wanted a simple dashboard that just showed me links to my homelab applications. A lot of dashboard applications I came across added lots of overhead to the mix, statistics, API calls to the applications, etc.

With HomeDash my goals are:

  • Single binary;
  • Sane default settings so you need minimal configuration;
  • Multiple sources reporting in automatically;
  • As automated as possible;
  • Regularly refreshing the list of applications;
  • Useable as a container;

HomeDash currently has two components: HomeDash server and a sidecar application.

The server provides the dashboard & API. The sidecar application regularly sends an updated list of containers that are HomeDash enabled and actively running on the server that the sidecar is running on.

The sidecar application reads the labels for all containers on the same machine using the Docker API. Whenever a container has at least a label with the name homedash.name, it adds that application to the list.

Right now, other (optional) labels include:

  • homedash.url
  • homedash.icon
  • homedash.comment

See the sidecar README for more and up-to-date details.

The icons

Originally I thought about using some sort of icon pack like SimpleIcons but soon found that had severe limitations. Open Source and reuseability to the rescue though!

The Heimdall dashboard has a seperate repository for icons and application information. I decided that, when you start HomeDash, it will download the archive from that respository and re-use the icons. Upon subsequent restarts, the icons from the cache directory will be used. In case you’re running the containerized version of HomeDash, you will need to bind a volume to the cache directory to ensure it survives a restart.


Minimal usage

Using HomeDash is supposed to be as easy as possible. If you follow the steps below, you should be setup and ready to use it in a couple of minutes.

Assuming you want to try it with your server and sidecar on the same system.

  1. Download the latest HomeDash server & sidecar application application binaries;
    1$> curl -L -o homedash https://github.com/mvdkleijn/homedash/releases/download/v1.0.0/homedash-linux-arm64
    2$> curl -L -o homedash-sidecar https://github.com/mvdkleijn/homedash-sidecar/releases/download/v1.0.0/homedash-sidecar-linux-arm64
  2. Run the HomeDash server application;
    1$> ./homedash
  3. Configure one of your application containers to have the following labels:
    1# Docker compose example
    3  - "homedash.name=Adguard"
    4  - "homedash.url=http://localhost:8800"
    5  - "homedash.icon=adguard"
  4. Run the sidecar application;
    1$> export HOMEDASH-SERVER=http://localhost:8080 # or whatever the equivalent is for your system
    2$> ./homedash-sidecar
  5. Go to http://localhost:8080 and see the dashboard;

Docker compose example

A slightly more complex setup can be achieved easily with Docker Compose. The example below provides the server and sidecar on the same system. It uses an existing Traefik reverse proxy in front of the dashboard and expects Tecnativa’s Docker socket proxy to be available.

Note: the reason for using the https://github.com/tecnativa/docker-socket-proxy mentioned above is for protecting the Docker socket against unauthorized access, since direct access to your Docker socket is usually not a good idea security wise.

Feel free to adjust where desired though.

 1version: "3"
 4  traefik:
 5    external: true
 8  server:
 9    image: ghcr.io/mvdkleijn/homedash:latest
10    container_name: homedash
11    volumes:
12      - ./data:/homedash
13    environment:
14      - USER_UID=65532
15      - USER_GID=65532
16    restart: always
17    networks:
18      - traefik
19    labels:
20      - "traefik.enable=true"
21      - "traefik.http.routers.homedash.entrypoints=web"
22      - "traefik.http.routers.homedash.rule=Host(`dash.example.com`)"
23      - "traefik.http.services.homedash.loadbalancer.server.port=8080"
24      - "homedash.name=HomeDash"
25      - "homedash.url=http://dash.example.com"
26      - "homedash.icon=homedash"
28  sidecar:
29    image: ghcr.io/mvdkleijn/homedash-sidecar:latest
30    container_name: homedash-sidecar
31    environment:
32      - USER_UID=65532
33      - USER_GID=65532
34      - HOMEDASH_SERVER=http://dash.example.com
35      - DOCKER_HOST=http://host.docker.internal:2375
36    restart: always
37    network_mode: host
38    extra_hosts:
39      - "host.docker.internal:host-gateway"
40    labels:
41      - "traefik.enable=false"
42    depends_on:
43      server:
44        condition: service_healthy

Getting support

You can find the Github repositories at:

There you can read more details in the README files, report issues and/or collaborate in its development.

Currently supported stack:


HomeDash is made available under the MPL-2.0 license. The full details are available from the LICENSE file.