It’s a common frustration: you’ve set up a Samba server, perhaps using Docker for convenience, and you know it’s running because you can access it directly (e.g., \\server-ip or smb://server-ip). However, it stubbornly refuses to show up in Windows File Explorer’s “Network” section, Linux’s “Other Locations” in Nautilus/Files, or macOS Finder’s “Network” view.

I’ve been using Samba in Docker for a long time, specifically the popular dperson/samba image. While functional for direct access, network discovery was consistently an issue across all my operating systems. This meant users had to know the server’s exact address, which isn’t ideal for ease of use.

The Challenge of Network Discovery

Network discovery for Samba shares relies on a few key protocols:

1. WS-Discovery (WSD): Modern Windows versions (Vista and later) primarily use WSD for network discovery of services. wsdd2 is a common daemon that implements this for Samba.
2. mDNS/DNS-SD (Bonjour/Avahi): macOS relies heavily on Bonjour (which uses mDNS/DNS-SD) for service discovery. Linux systems typically use Avahi, a compatible implementation.
3. NetBIOS Name Service: Older Windows systems and some configurations might still use NetBIOS for name resolution and discovery, though it’s less common for discovery in modern networks.

The dperson/samba image, while an excellent Samba server, doesn’t have these discovery mechanisms enabled out-of-the-box in a way that seamlessly integrates. I noticed a config file named _etc_avahi_services_samba.service in its repository, but documentation on its use was sparse, and it didn’t seem to be active by default or solve the WSD issue for Windows clients.

One approach could be to set up separate Docker containers for Avahi and a WSD service, linking them to your Samba container. However, this adds complexity to your Docker setup.

The Simpler Solution: A Docker Image with Built-in Discovery

A much cleaner solution is to use a Docker image that bundles Samba with Zeroconf (Avahi for mDNS) and WSD (via wsdd2) support. I found an excellent candidate: servercontainers/samba.

This image comes with Avahi and WSDD2 enabled by default, significantly simplifying the setup for discoverability.

GitHub Repository: https://github.com/ServerContainers/samba

Migrating to servercontainers/samba

Here’s how I replaced my old Samba Docker container with the new one:

1. Stop and Remove the Old Samba Service:

First, ensure your old Samba container is stopped to free up any network ports or container names.

# Replace 'your_old_samba_container_name' with the actual name or ID

docker stop your_old_samba_container_name

2. Create docker-compose.yml for the New Service:

Create a docker-compose.yml file with the following content. Be sure to customize the paths, user credentials, hostname, timezone, and especially the WSDD2_PARAMETERS to match your environment.

version: '3.8'

services:
  samba:
    image: ghcr.io/servercontainers/samba:latest
    container_name: samba_server
    hostname: NAS # Change this to your desired server hostname (visible on the network)
    # Using host network mode is highly recommended for Samba.
    # It simplifies service discovery (Avahi, WSDD2) by allowing the container
    # to use the host's network stack directly, avoiding port mapping complexities.
    network_mode: host
    restart: always
    environment:
      # --- User Credentials and ID ---
      # Replace 'jacobhere' with your desired username and 'password_for_user' with a strong password.
      # You can add multiple users by duplicating this line with different usernames.
      - ACCOUNT_jacobhere=password_for_user
      # Set the User ID (UID) for the created user.
      # This should ideally match the UID of the user who owns the files on your host system
      # to avoid permission issues. Find it with `id -u your_host_username`.
      - UID_jacobhere=1000
      # The primary group for 'jacobhere' will typically also be created with GID matching the UID.

      # --- Timezone (Optional but Recommended) ---
      # Set this to your local timezone for accurate log timestamps.
      # Find your timezone: <https://en.wikipedia.org/wiki/List_of_tz_database_time_zones>
      - TZ=America/Chicago # Example: America/Los_Angeles, Europe/Berlin

      # --- Share Definitions ---
      # Format: SAMBA_VOLUME_CONFIG_<ShareNameInConfig>=[Network Share Name]; path=<path inside container>; valid users=<userlist>; browseable=yes; read only=no; guest ok=no
      # <ShareNameInConfig> is an internal identifier, can be the same as [Network Share Name]
      # [Network Share Name] is what users will see.
      # path=<path inside container> is where the share is located *inside* the Docker container.
      # valid users=<userlist> comma-separated list of users who can access this share.
      - SAMBA_VOLUME_CONFIG_Raid=[Raid]; path=/shares/zfs_mirror/Raid; valid users=jacobhere; browseable=yes; read only=no; guest ok=no
      - SAMBA_VOLUME_CONFIG_Unraid=[Unraid]; path=/shares/zfs/Unraid; valid users=jacobhere; browseable=yes; read only=no; guest ok=no
      - SAMBA_VOLUME_CONFIG_Media=[Media]; path=/shares/zfs/Media; valid users=jacobhere; browseable=yes; read only=no; guest ok=no

      # --- Service Discovery (Enabled by Default) ---
      # Avahi (for macOS/Linux discovery) and WSDD2 (for Windows discovery) are enabled by default.
      # To disable them, you would set AVAHI_DISABLE=true or WSDD2_DISABLE=true.
      # Since we want them enabled, these variables should NOT be set or set to false.

      # IMPORTANT: WSDD2 Network Interface
      # WSDD2 needs to know which network interface to announce on.
      # Replace 'ens18' with your server's primary network interface name.
      # Find it on your Linux host with `ip addr` or `ifconfig`. Common names: eth0, eno1, enp3s0, etc.
      - WSDD2_PARAMETERS=-i ens18

    volumes:
      # Map your host directories (where your data resides) to the paths used inside the container for the shares.
      # The path on the left is on your host machine; the path on the right is inside the container.
      - /mnt/zfs_mirror:/shares/zfs_mirror # Host path : Container path
      - /mnt/zfs:/shares/zfs             # Host path : Container path
      # Optional: Persist Samba's internal configuration and state.
      # This can be useful for more complex setups or to preserve Samba-specific metadata.
      # - ./samba_config:/var/lib/samba # Host path : Container path (creates 'samba_config' directory in the same folder as docker-compose.yml)

    # --- Port Mapping (Not needed with network_mode: host) ---
    # If you were NOT using network_mode: host, you would need to expose Samba's ports:
    # ports:
    #   - "137:137/udp" # NetBIOS Name Service
    #   - "138:138/udp" # NetBIOS Datagram Service
    #   - "139:139/tcp" # NetBIOS Session Service (SMB over NetBIOS)
    #   - "445:445/tcp" # SMB over TCP (Direct Host)

    # --- Capabilities (Generally not needed with network_mode: host) ---
    # Adding CAP_NET_ADMIN might be necessary for wsdd2 if not using host network mode
    # or if the container isn't running as root (which this one typically does by default).
    # It doesn't hurt to include it with host network mode.
    cap_add:
      - CAP_NET_ADMIN

Key docker-compose.yml considerations:

• hostname: This will be the name your Samba server announces on the network.
• network_mode: host: This is crucial for easy service discovery. It makes the container share the host’s network stack, so Avahi and WSDD2 can correctly announce services.
• ACCOUNT_username=password and UID_username: Set up your users. Matching the UID to your host file owner’s UID can prevent permission issues.
• TZ: Setting your timezone is good practice for log file accuracy.
• SAMBA_VOLUME_CONFIG_...: Define your shares clearly.
• WSDD2_PARAMETERS=-i ens18: This is critical! You must replace ens18 with the actual network interface name of your Docker host (e.g., eth0, eno1). You can find this by running ip addr or ifconfig on your host system. WSDD2 needs this to bind to the correct interface for announcements.
• volumes: Ensure the host paths correctly point to your data.

3. Start the New Samba Service:

Navigate to the directory where you saved your docker-compose.yml file and run:

Bash

docker-compose up -d

The -d flag runs the container in detached mode (in the background).

4. Verify Discovery:

Wait a minute or two for the services to initialize and announce themselves. Then check:

• Windows: Open File Explorer and click on “Network.” Your Samba server (e.g., “NAS”) should appear.
• Linux (GNOME/Nautilus): Open Files (Nautilus) and look under “Other Locations.” Your server should be listed.
• macOS: Open Finder and check the “Network” section in the sidebar. Your server should be visible.

If it’s working, you should be able to click on the server name and browse its shares without needing to manually type the IP address or SMB path!

Conclusion

Switching to the servercontainers/samba Docker image resolved my long-standing Samba discovery issues across Windows, Linux, and macOS. The built-in support for Avahi and WSDD2, combined with the recommended network_mode: host setting, makes setup straightforward and reliable.

If you’ve been struggling with an invisible Samba server, I highly recommend giving this Docker image and configuration a try. It significantly improves the user experience for everyone on your network.