https://github.com/stefapi/docker-dashy-helper

An Helper module to create a Dashy portal from a docker system
https://github.com/stefapi/docker-dashy-helper
Last synced: 28 days ago
JSON representation
An Helper module to create a Dashy portal from a docker system
Host: GitHub
URL: https://github.com/stefapi/docker-dashy-helper
Owner: stefapi
License: apache-2.0
Created: 2022-01-11T13:19:09.000Z (over 4 years ago)
Default Branch: main
Last Pushed: 2022-03-30T22:02:27.000Z (over 4 years ago)
Last Synced: 2025-02-22T23:27:29.504Z (over 1 year ago)
Language: Python
Size: 41 KB
Stars: 0
Watchers: 1
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project

README

          


# 🐳 Docker-Dashy-Helper

**Automatically generate Dashy dashboards from Docker container labels**

[![Docker Hub](https://img.shields.io/docker/pulls/stefapi/docker-dashy-helper?style=flat-square&logo=docker)](https://hub.docker.com/r/stefapi/docker-dashy-helper)

[![GitHub Stars](https://img.shields.io/github/stars/stefapi/docker-dashy-helper?style=flat-square&logo=github)](https://github.com/stefapi/docker-dashy-helper/stargazers)

[![License](https://img.shields.io/github/license/stefapi/docker-dashy-helper?style=flat-square)](LICENSE)

[![Build Status](https://img.shields.io/github/actions/workflow/status/stefapi/docker-dashy-helper/image.yml?style=flat-square&logo=github)](https://github.com/stefapi/docker-dashy-helper/actions)

*A smart helper container that automatically exposes all your Docker containers as beautiful [Dashy](https://github.com/Lissy93/dashy) dashboard elements*

[Features](#-features) • [Quick Start](#-quick-start) • [Configuration](#-configuration) • [Examples](#-examples) • [Contributing](#-contributing)



---

## 📋 Table of Contents

- [✨ Features](#-features)

- [🚀 Quick Start](#-quick-start)

- [📦 Installation](#-installation)

- [🔧 Configuration](#-configuration)

  - [Site Definition](#site-definition)

  - [Container Definition](#container-definition)

  - [Groups Definition](#groups-definition)

- [💻 Command Line Arguments](#-command-line-arguments)

- [📚 Examples](#-examples)

- [🏗️ Building](#️-building)

- [🔍 Troubleshooting](#-troubleshooting)

- [🤝 Contributing](#-contributing)

- [📄 License](#-license)

## ✨ 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:

```bash

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

```bash

docker pull stefapi/docker-dashy-helper

```

### Using Docker Compose

See our [examples directory](examples/) for complete Docker Compose configurations.

### Building from Source

```bash

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

```bash

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`

```bash

# 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

   ```bash

   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

```bash

docker-dashy.grp-prop=color=`#808080`,collapsed=`true`,sortBy=`most-used`

```

Available properties follow Dashy's `displayData` specification. See the [Dashy documentation](https://github.com/Lissy93/dashy/blob/master/docs/configuring.md#sectiondisplaydata-optional) for all options.

#### Example Group Configuration

```yaml

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

```bash

# 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

```yaml

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

```bash

# 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](examples/).

## 🏗️ Building

### Prerequisites

- Docker

- Git

### Build Steps

```bash

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

```bash

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

```

#### Dashboard Not Updating

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

   ```bash

   docker logs docker-dashy-helper

   ```

2. Verify the configuration file is being generated:

   ```bash

   cat /path/to/dashy-conf.yml

   ```

3. Ensure containers have the correct labels:

   ```bash

   docker inspect  | 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

- 📖 Check the [examples directory](examples/) for working configurations

- 🐛 Report issues on [GitHub Issues](https://github.com/stefapi/docker-dashy-helper/issues)

- 💬 Join discussions in [GitHub Discussions](https://github.com/stefapi/docker-dashy-helper/discussions)

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) 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](LICENSE) file for details.

## 🙏 Acknowledgments

- [Dashy](https://github.com/Lissy93/dashy) - The amazing dashboard this project enhances

- [Traefik](https://traefik.io/) - For inspiration on label-based configuration

- All contributors who help improve this project

---



**[⬆ Back to Top](#-docker-dashy-helper)**

Made with ❤️ by [stefapi](https://github.com/stefapi)
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/stefapi/docker-dashy-helper

Awesome Lists containing this project

README
