Automatically generate Dashy dashboards from Docker container labels
A smart helper container that automatically exposes all your Docker containers as beautiful Dashy dashboard elements
Features β’ Quick Start β’ Configuration β’ Examples β’ Contributing
- β¨ Features
- π Quick Start
- π¦ Installation
- π§ Configuration
- π» Command Line Arguments
- π Examples
- ποΈ Building
- π Troubleshooting
- π€ Contributing
- π License
- π Automatic Discovery: Automatically detects and configures Docker containers
- π·οΈ Label-Based Configuration: Uses Docker labels for easy setup (similar to Traefik)
- π Traefik Integration: Seamlessly works with Traefik reverse proxy
- π¨ Customizable Themes: Support for multiple Dashy themes and icon sizes
- π Multi-Language: Configurable language support
- π Status Monitoring: Built-in health checks and status indicators
- π Smart URL Detection: Automatic URL generation from container configuration
- π± Responsive Design: Works perfectly with Dashy's responsive interface
- π§ Real-Time Updates: Dynamic configuration updates when containers change
Get up and running in under 2 minutes:
# 1. Create an empty configuration file
touch /opt/conf.yml
# 2. Start Docker-Dashy-Helper
docker run -d \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /opt/conf.yml:/app/conf.yml \
stefapi/docker-dashy-helper /app/conf.yml
# 3. Launch Dashy dashboard
docker run -d \
-l 'docker-dashy.dashy' \
-p 80:80 \
-v /opt/conf.yml:/app/public/conf.yml \
lissy93/dashy:latest
π That's it! Your dashboard is now available at http://localhost
docker pull stefapi/docker-dashy-helper
See our examples directory for complete Docker Compose configurations.
git clone https://github.com/stefapi/docker-dashy-helper
cd docker-dashy-helper
docker build -t docker-dashy-helper .
All configuration is read from container labels (similar to Traefik) and the Dashy configuration file is only written when labels change.
These labels are used on the Dashy container to configure the overall dashboard:
Label | Description | Example |
---|---|---|
docker-dashy.site |
Site name | docker-dashy.site=My Dashboard |
docker-dashy.comment |
Site description | docker-dashy.comment=My awesome dashboard |
docker-dashy.footer |
Footer text | docker-dashy.footer=Powered by Dashy |
docker-dashy.options |
App configuration options | docker-dashy.options=statusCheck=true,layout=horizontal |
docker-dashy.dashy |
Mark as Dashy container for restart | docker-dashy.dashy=true |
docker-dashy.options=statusCheck=`true`,faviconApi=`local`,layout=`horizontal`
These labels are used on service containers that you want to display on the Dashy dashboard:
Add navigation links using: docker-dashy.navlink.[item].link
# Syntax: Url(`[display_text]`, `[url]`)
docker-dashy.navlink.admin.link=Url(`Admin Panel`, `https://admin.example.com`)
Label | Description | Example |
---|---|---|
docker-dashy.enable |
Enable/disable container in dashboard | docker-dashy.enable=true |
docker-dashy.label |
Custom display name | docker-dashy.label=My Service |
docker-dashy.url |
Custom URL override | docker-dashy.url=https://service.local:8080 |
docker-dashy.comment |
Service description | docker-dashy.comment=My awesome service |
docker-dashy.icon |
Icon specification | docker-dashy.icon=si-docker |
docker-dashy.color |
Text color | docker-dashy.color=#ffffff |
docker-dashy.bgcolor |
Background color | docker-dashy.bgcolor=#333333 |
docker-dashy.status |
Status check configuration | docker-dashy.status=true |
docker-dashy.group |
Group assignment | docker-dashy.group=Web Services |
- Custom URL:
docker-dashy.url=https://myservice.example.com:8080/path
- Traefik Labels: Automatically reads Traefik router configurations
traefik.http.routers.myservice.rule=Host(`myservice.example.com`)
- Auto-detection: Inspects container ports and builds URL using hostname
- Basic:
docker-dashy.status=true
(uses service URL) - Custom URL:
docker-dashy.status=https://health.example.com/check
- Internal:
docker-dashy.status=internal
(uses container internal IP)
β οΈ Note: When usinginternal
status checks, ensure the Dashy container can access the target container's internal IP address.
Organize your services into logical groups for better dashboard organization.
Label | Description | Example |
---|---|---|
docker-dashy.group |
Group name | docker-dashy.group=Web Services |
docker-dashy.grp-icon |
Group icon | docker-dashy.grp-icon=fas fa-globe |
docker-dashy.grp-prop |
Group properties | docker-dashy.grp-prop=collapsed=false,sortBy=alphabetical |
docker-dashy.grp-prop=color=`#808080`,collapsed=`true`,sortBy=`most-used`
Available properties follow Dashy's displayData
specification. See the Dashy documentation for all options.
services:
nginx:
image: nginx
labels:
- "docker-dashy.enable=true"
- "docker-dashy.label=Web Server"
- "docker-dashy.group=Web Services"
- "docker-dashy.grp-icon=fas fa-globe"
- "docker-dashy.grp-prop=collapsed=false,sortBy=alphabetical"
Docker-Dashy-Helper accepts one mandatory parameter (configuration file path) and several optional parameters:
Argument | Description |
---|---|
config_file |
Path to the Dashy configuration file |
Short | Long | Description | Default | Example |
---|---|---|---|---|
-d |
--disable |
Disable automatic container addition | false |
-d |
-n |
--hostname |
Hostname for default URLs | localhost |
-n myhost.local |
-l |
--lang |
Dashboard language | en |
-l fr |
-s |
--size |
Icon size | medium |
-s large |
-t |
--theme |
Dashboard theme | Default |
-t material |
-k |
--keep |
Keep existing config values | false |
-k |
-r |
--reset |
Reset config at startup | false |
-r |
-f |
--force |
Force reset at each loop | false |
-f |
-w |
--wait |
Scan interval (seconds) | 10 |
-w 30 |
# Basic usage
docker-dashy-helper /app/conf.yml
# With custom settings
docker-dashy-helper -n myhost.local -l fr -s large -t material /app/conf.yml
# Disable auto-discovery (manual mode)
docker-dashy-helper -d /app/conf.yml
# Development mode with frequent resets
docker-dashy-helper -f -w 5 /app/conf.yml
version: "3.8"
services:
# Docker-Dashy-Helper
docker-dashy-helper:
image: stefapi/docker-dashy-helper:latest
command: ["-n", "localhost", "-l", "en", "/app/conf.yml"]
volumes:
- ./dashy-conf.yml:/app/conf.yml
- /var/run/docker.sock:/var/run/docker.sock
restart: unless-stopped
# Dashy Dashboard
dashy:
image: lissy93/dashy:latest
labels:
- "docker-dashy.enable=true"
- "docker-dashy.site=true"
- "docker-dashy.comment=My Dashboard"
- "docker-dashy.dashy=true"
ports:
- "4000:80"
volumes:
- ./dashy-conf.yml:/app/public/conf.yml
restart: unless-stopped
# Example Service
nginx:
image: nginx:alpine
labels:
- "docker-dashy.enable=true"
- "docker-dashy.label=Web Server"
- "docker-dashy.icon=si-nginx"
- "docker-dashy.group=Web Services"
- "docker-dashy.status=true"
ports:
- "8080:80"
restart: unless-stopped
# 1. Start Docker-Dashy-Helper
docker run -d \
--name docker-dashy-helper \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /opt/dashy_conf.yml:/app/conf.yml \
stefapi/docker-dashy-helper -l en -s large /app/conf.yml
# 2. Start Dashy Dashboard
docker run -d \
--name dashy \
-l 'docker-dashy.dashy=true' \
-p 5000:80 \
-v /opt/dashy_conf.yml:/app/public/conf.yml \
lissy93/dashy:latest
# 3. Start a service (Portainer example)
docker run -d \
--name portainer \
-l 'docker-dashy.enable=true' \
-l 'docker-dashy.label=Portainer' \
-l 'docker-dashy.icon=si-portainer' \
-l 'docker-dashy.group=Management' \
-p 9000:9000 \
-v /var/run/docker.sock:/var/run/docker.sock \
-v portainer_data:/data \
portainer/portainer-ce
For more examples, see the examples directory.
- Docker
- Git
# Clone the repository
git clone https://github.com/stefapi/docker-dashy-helper
cd docker-dashy-helper
# Build the Docker image
docker build -t docker-dashy-helper .
# Or build for multiple platforms
docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t docker-dashy-helper .
If you're running on a system with AppArmor and encounter D-Bus message errors:
docker run --privileged stefapi/docker-dashy-helper
-
Check if Docker-Dashy-Helper is running:
docker logs docker-dashy-helper
-
Verify the configuration file is being generated:
cat /path/to/dashy-conf.yml
-
Ensure containers have the correct labels:
docker inspect <container_name> | grep -A 10 Labels
- Verify
docker-dashy.enable=true
is set on service containers - Check that the Docker socket is properly mounted
- Ensure the helper has access to read container labels
- π Check the examples directory for working configurations
- π Report issues on GitHub Issues
- π¬ Join discussions in GitHub Discussions
We welcome contributions! Please see our Contributing Guide for details.
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature
- Make your changes
- Test your changes
- Commit:
git commit -m 'Add amazing feature'
- Push:
git push origin feature/amazing-feature
- Open a Pull Request
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
- Dashy - The amazing dashboard this project enhances
- Traefik - For inspiration on label-based configuration
- All contributors who help improve this project
Made with β€οΈ by stefapi