🐳 Dashy Docker Sync - Realtime sync of your docker containers to your Dashy Dashboard

[jeppestaerk]

Dashy Docker Sync

Dynamically update your Dashy dashboard configuration based on Docker container lifecycle events. This tool listens to Docker events and automatically adds or removes services from a specified section in your Dashy conf.yml.

What it does

• Automatic Discovery: Adds and removes services in Dashy as Docker containers start and stop.
• Label-Driven: Highly configurable behavior based on Docker container labels.
• Expose containers explicitly via labels.
• Optionally expose all containers by default.
• Override detected ports using a specific label.
• Customizable Templates: Define custom URL, title, and icon paths for your Dashy items using templates.
• Startup Reset: Optionally clear the managed Dashy section on startup for a clean slate.
• Flexible Configuration: All settings are manageable via environment variables.

Quick start

I’ve packaged this as a Docker image so it can run alongside Dashy. Here’s a minimal docker-compose.yml example:

services:
  dashy:
    image: lissy93/dashy:latest
    ports:
      - "8080:8080"
    volumes:
      - ./user-data:/app/user-data

  dashy-sync:
    image: ghcr.io/jeppestaerk/dashy-docker-sync:latest
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro # Listens on docker events and updates realtime
      - ./config/conf.yml:/config/conf.yml # Dashy conf.yml
    environment:
      - DASHY_DOCKER_URL_HOST=localhost # Hostname or IP
      - DASHY_DOCKER_URL_TEMPLATE=http://{host}:{port} # Port defaults to `dashy.port` or the first port
      # To use traefik loadbalancer port:
      # - DASHY_DOCKER_PORT_LABEL_REGEX=^traefik\.http\.services\.[a-zA-Z0-9_-]+\.loadbalancer\.server\.port$
      # To only include services that are enabled on traefik:
      # - DASHY_DOCKER_LABEL_REGEX=^traefik\.enable$
      # To add reverse proxy domain:
      # - DASHY_DOCKER_URL_HOST=myhomelab.io
      # - DASHY_DOCKER_URL_TEMPLATE=https://{name}.{host} # Name defaults to container_name
      # To expose all containers by default
      # - DASHY_EXPOSED_BY_DEFAULT=true

  httpbin:
    image: kennethreitz/httpbin
    container_name: httpbin # {name} to use in Dashy
    restart: unless-stopped
    ports:
      - "8080:80" # First port is use by default as {port} if `dashy.port` is not set.
    labels:
      - dashy.enabled=true
      - dashy.port=8080 # Overwrites {port}

Add this to any container you want surfaced in Dashy:

  labels:
    - dashy.enabled=true # Can be changed with DASHY_DOCKER_LABEL_REGEX
    - dashy.port=8080 # Can be changed with DASHY_DOCKER_PORT_LABEL_REGEX

This would update the Dashy config file with:

sections:
- name: Docker Containers # Can be changed with DASHY_DOCKER_SECTION_NAME
  icon: https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/docker.svg
  displayData:
    color: '#1D63ED'
  items:
  - title: httpbin # Can be changed with DASHY_DOCKER_TITLE_TEMPLATE
    url: http://localhost:8080 # Can be changed with DASHY_DOCKER_URL_TEMPLATE
    icon: hl-httpbin # Can be changed with DASHY_DOCKER_ICON_TEMPLATE

When you deploy a new container or change those values, the sync tool will automatically regenerate the section in conf.yml and Dashy will pick up the changes without any manual editing

🔧 More env vars & advanced options

Variable	Description	Default Value
DASHY_CONFIG_PATH	Full path inside the container to your Dashy conf.yml file.	/config/dashy-config.yml
DASHY_LOG_LEVEL	Logging verbosity (e.g., DEBUG, INFO, WARNING, ERROR).	INFO
DASHY_RESET_ON_START	If true, the specified Docker section in Dashy will be cleared of items on application startup.	true
DASHY_DOCKER_SECTION_NAME	The name of the section in your Dashy config where Docker container items will be managed.	Docker Containers
DASHY_EXPOSED_BY_DEFAULT	If true, all running containers will be considered for Dashy unless explicitly excluded by other logic. If false, only containers with a matching DASHY_DOCKER_LABEL_REGEX label will be considered.	false
DASHY_DOCKER_LABEL_REGEX	A regex pattern to match against container label keys. If DASHY_EXPOSED_BY_DEFAULT is false, a container must have at least one label key matching this regex to be included.	`^(?:dashy$
DASHY_DOCKER_IGNORE_LABEL_REGEX	A regex pattern to match against container label keys. If any label key matches this regex AND its value is explicitly "true" (case-insensitive), the container will be skipped, regardless of other settings. If the value is "false" or anything else, this specific ignore label is ignored.	^dashy\.ignore$
DASHY_DOCKER_PORT_LABEL_REGEX	A regex pattern to match against container label keys for specifying the port. The value of this label will be used as the port.	^dashy\.port$
DASHY_DOCKER_URL_HOST	The hostname or IP to use in the {host} placeholder of the DASHY_DOCKER_URL_TEMPLATE.	localhost
DASHY_DOCKER_URL_TEMPLATE	Template for generating the item URL. Placeholders: {host}, {port}, {name} (container name).	http://{host}:{port}
DASHY_DOCKER_TITLE_TEMPLATE	Template for generating the item title. Placeholder: {name} (container name).	{name}
DASHY_DOCKER_ICON_TEMPLATE	Template for generating the item icon URL/path. Placeholder: {name}. Can point to local Dashy icons (e.g., png/{name}.png) or external URLs.	hl-{name}
DOCKER_SOCKET	Path to the Docker socket.	unix://var/run/docker.sock

Advance start

🐳 Full docker compose exsample

services:
  dashy-docker-sync:
    image: ghcr.io/jeppestaerk/dashy-docker-sync:latest
    container_name: dashy-docker-sync
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      # IMPORTANT: Replace '/path/to/your/dashy/conf.yml' with the actual path
      # to your Dashy configuration file on the host machine.
      # Example: - /mnt/user/appdata/dashy/user-data/conf.yml:/config/conf.yml
      - ./config/conf.yml:/config/conf.yml
    environment:
      # --- Label Matching for Inclusion/Exclusion/Port ---
      # If DASHY_EXPOSED_BY_DEFAULT=false, containers need a label matching this regex to be included.
      - DASHY_DOCKER_LABEL_REGEX=^(?:dashy$|dashy\..+)
      # If a container has a label matching this regex AND its value is "true", it will be skipped.
      - DASHY_DOCKER_IGNORE_LABEL_REGEX=^dashy\.ignore$
      # Label key to find the port for the service URL.
      - DASHY_DOCKER_PORT_LABEL_REGEX=^dashy\.port$

      # --- URL and Item Generation Templates ---
      # Hostname/IP used in DASHY_DOCKER_URL_TEMPLATE's {host} placeholder.
      # Or set to your domain if services are exposed publicly/via reverse proxy.
      - DASHY_DOCKER_URL_HOST=localhost
      - DASHY_DOCKER_URL_TEMPLATE=http://{host}:{port}
      - DASHY_DOCKER_TITLE_TEMPLATE={name}
      - DASHY_DOCKER_ICON_TEMPLATE=hl-{name} # Example: hl-mycontainer for Homarr icons, or mdi-docker, or full URL

  dashy:
    image: lissy93/dashy
    container_name: Dashy
    volumes:
      - ./config/conf.yml:/app/user-data/conf.yml
    ports:
      - 4000:8080
    environment:
      - NODE_ENV=production
      - UID=1000
      - GID=1000
    restart: unless-stopped
    healthcheck:
      test: ['CMD', 'node', '/app/services/healthcheck']
      interval: 1m30s
      timeout: 10s
      retries: 3
      start_period: 40s
    labels:
      - dashy.ignore=true # Skip this container in the list

  httpbin:
    image: kennethreitz/httpbin
    container_name: httpbin # Title to use in Dashy
    restart: unless-stopped
    ports:
      - "8080:80"
    labels:
      - dashy.port=8080 # Include this container and use port in the URL template

See more info here: https://github.com/jeppestaerk/dashy-docker-sync/blob/main/README.md