HomeDash
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.urlhomedash.iconhomedash.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.
Usage
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.
- 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;
1$> ./homedash - 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;
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"
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
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:
- Go versions, see: https://endoflife.date/go
- Architectures: amd64, arm64
Licensing
HomeDash is made available under the MPL-2.0 license. The full details are available from the LICENSE file.