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.
- 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.
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;
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:
See the sidecar README for more and up-to-date details.
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.
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.
- 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
- Run the HomeDash server application;
- Configure one of your application containers to have the following labels:
1# Docker compose example 2labels: 3 - "homedash.name=Adguard" 4 - "homedash.url=http://localhost:8800" 5 - "homedash.icon=adguard"
- Run the sidecar application;
1$> export HOMEDASH-SERVER=http://localhost:8080 # or whatever the equivalent is for your system 2$> ./homedash-sidecar
- Go to http://localhost:8080 and see the dashboard;
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" 2 3networks: 4 traefik: 5 external: true 6 7services: 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" 27 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
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:
- Go versions, see: https://endoflife.date/go
- Architectures: amd64, arm64