Skip to content

stefapi/docker-dashy-helper

Repository files navigation

🐳 Docker-Dashy-Helper

Automatically generate Dashy dashboards from Docker container labels

Docker Hub GitHub Stars License Build Status

A smart helper container that automatically exposes all your Docker containers as beautiful Dashy dashboard elements

Features β€’ Quick Start β€’ Configuration β€’ Examples β€’ Contributing


πŸ“‹ Table of Contents

✨ Features

  • πŸ”„ 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

πŸš€ Quick Start

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

πŸ“¦ Installation

Using Docker Hub (Recommended)

docker pull stefapi/docker-dashy-helper

Using Docker Compose

See our examples directory for complete Docker Compose configurations.

Building from Source

git clone https://github.com/stefapi/docker-dashy-helper
cd docker-dashy-helper
docker build -t docker-dashy-helper .

πŸ”§ Configuration

All configuration is read from container labels (similar to Traefik) and the Dashy configuration file is only written when labels change.

Site Definition

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

Options Syntax

docker-dashy.options=statusCheck=`true`,faviconApi=`local`,layout=`horizontal`

Container Definition

These labels are used on service containers that you want to display on the Dashy dashboard:

Navigation Links

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`)

Service Items

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

URL Detection Priority

  1. Custom URL: docker-dashy.url=https://myservice.example.com:8080/path
  2. Traefik Labels: Automatically reads Traefik router configurations
    traefik.http.routers.myservice.rule=Host(`myservice.example.com`)
  3. Auto-detection: Inspects container ports and builds URL using hostname

Status Checks

  • 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 using internal status checks, ensure the Dashy container can access the target container's internal IP address.

Groups Definition

Organize your services into logical groups for better dashboard organization.

Group Labels

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

Group Properties Syntax

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.

Example Group Configuration

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"

πŸ’» Command Line Arguments

Docker-Dashy-Helper accepts one mandatory parameter (configuration file path) and several optional parameters:

Required Arguments

Argument Description
config_file Path to the Dashy configuration file

Optional Arguments

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

Usage Examples

# 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

πŸ“š Examples

Complete Docker Compose Setup

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

Manual Docker Commands

# 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.

πŸ—οΈ Building

Prerequisites

  • Docker
  • Git

Build Steps

# 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 .

πŸ” Troubleshooting

Common Issues

AppArmor Compatibility

If you're running on a system with AppArmor and encounter D-Bus message errors:

docker run --privileged stefapi/docker-dashy-helper

Dashboard Not Updating

  1. Check if Docker-Dashy-Helper is running:

    docker logs docker-dashy-helper
  2. Verify the configuration file is being generated:

    cat /path/to/dashy-conf.yml
  3. Ensure containers have the correct labels:

    docker inspect <container_name> | grep -A 10 Labels

Services Not Appearing

  • 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

Getting Help

🀝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Start for Contributors

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Make your changes
  4. Test your changes
  5. Commit: git commit -m 'Add amazing feature'
  6. Push: git push origin feature/amazing-feature
  7. Open a Pull Request

πŸ“„ License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

πŸ™ Acknowledgments

  • Dashy - The amazing dashboard this project enhances
  • Traefik - For inspiration on label-based configuration
  • All contributors who help improve this project

⬆ Back to Top

Made with ❀️ by stefapi

About

An Helper module to create a Dashy portal from a docker system

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Sponsor this project

 

Packages

No packages published

Languages