Docker Compose with mDNS

FDM Monster provides container images with mDNS support, which requires the use of the Docker macvlan network driver. As a result, this functionality is limited to hosts running a Linux operating system.

Quick Start

Before setting up FDM Monster with mDNS you will need the following information.

• A name for the Docker network to create (you can use an existing macvlan network).
• The device label to bind the macvlan network to. For multi-homed systems ensure the device is on the network which will host FDM Monster.
• The network address in CIDR notation that the macvlan network will be part of (should match the network of the device).
• The network range in CIDR notation that specifies IP addresses available to containers attached to the macvlan network.
• The default gateway of the host interface.
• The IP address to assign to the container.

Using a helper script

Our setup script can create the required macvlan network and a functional docker-compose.yml. Download the FDM Monster helper script here: macvlan-setup.sh

Execute the script and respond to the prompts.

Run the container

docker compose -f FDMM-mDNS-docker-compose.yml up -d

Use your favorite browser to access http://fdmmonster.local

The Hard Way

"The Hard Way" assumes an understanding of linux and docker.

The following is a general guide based on the helper script. Please refer to docker command documentation and FDM Monster source for full descriptions of all syntax and options. In the examples below variable are denoted by ${..}. Please replace the entire variable syntax with correct values for your installation.

Create the macvlan bridge with these parameters:

• network like 192.168.50.0/24
• subnet like 192.168.50.128/25
• gateway like 192.168.50.1
• interface like eth0
• name like printer_macvlan_net

docker network create -d macvlan --subnet=${network} --ip-range=${subnet} --gateway=${gateway} -o parent=${interface} ${name}

Example of a fictive scenario:

  docker network create -d macvlan \
  --subnet=192.168.50.0/24 \
  --ip-range=192.168.50.128/25 \
  --gateway=192.168.50.1 \
  -o parent=eth0 \
  printer_macvlan_net

Create a docker-compose.yml similar to this template (replace ${name}, ${ip} on the right places):

# This section requires an explicit docker network that allows the container to
#  utilize an IP directly on the host interface. Reference macvlan setup at
#  https://docs.docker.com/engine/network/drivers/macvlan/ for details
service:
  fdm-monster-mdns:
    container_name: fdm-monster-mdns
    image: fdmmonster/fdm-monster:latest-mdns
    restart: unless-stopped
    environment:
      - SERVER_PORT=80   # Port for FDM Monster
    deploy:
      restart_policy:
        delay: 5s
        window: 120s
    networks:
      ${name}:               # rename to mach your config option below
        ipv4_address: ${ip}  # IP address to assign to FDM Monster container
    volumes:
      - fdmm-media:/app/media
      - fdmm-database:/app/database

volumes:
  fdmm-media:
    name: fdmm-media
  fdmm-database:
    name: fdmm-database

networks:
  ${name}:          # edit to suite as this is internal config
    external: true
    name: ${name}   # must match your macvlan bridge name

Run the container

docker compose -f docker-compose.yml up -d

Changes needed in docker-config.yml

The mDNS version requires use of docker's macvlan diver and minor changes to docker-compose.yml. Below are the important notes on these changes.

Image tags

mDNS support is available via a new image. This image can be selected by adding "-mdns" to any of the standard FMD Monster tags.

• latest-mdns
• x.y.z-mdns
• main-mdns
• develop-mdns
• x.y.z-rc1-1234-mdns

Network defintion

Within the docker-compose.yml, you must create a network definition. The defintion label does not need to match the macvlan network name. It is simply easier, and not harmful to use the same name. The name statement must match the macvlan bridge name.

Static IP vs DHCP

The FDM Monster container image does not support DHCP address assignment. If a static IP is not explicitly assigned, Docker will automatically select the next available IP address from the bridge network’s configured range. It is strongly recommended to either assign a static IP address to the container or configure a hostname to enable mDNS-based name resolution.

It is also highly recommended that the IP range provided to the mavlan bridge be removed from any DHCP scopes to prevent duplicate IP address use on your network.

No port definition

No port definition is used in the mDNS docker-compose.yml. There are 2 reasons for this:

• The container "lives" on the host's native network with a unique, network accessible MAC address and IP. This means that all open ports on the container are accessible on the network.
• Port mapping is not supported by the macvlan driver.