ServerContainers samba puts a Time Machine capable share in Alpine

The point of the image is Apple clients, not Samba itself

Samba is not a scarce thing to run. A Samba server on a Raspberry Pi or a NAS appliance is a solved problem, so the question worth asking is why this container exists. The readme gives the answer in its opening lines. The image is Samba on Alpine with timemachine, zeroconf through avahi, and WSD, Web Services for Devices, through wsdd2. Time Machine support is the reason a lot of people end up here, because Apple clients need specific Samba configuration and a protocol advertisement that a generic Samba install does not give you. The project description frames the same three pieces, avahi, wsdd2 and time machine, as optional additions to the base container. So the value proposition is narrow and concrete: it is the packaging work of getting a Samba daemon to satisfy macOS and iOS clients, plus the discovery mechanisms those clients use to find the server on a network, delivered as a single container image. If you do not need Apple clients to work, you are paying for work you do not need.

Tag names carry the Alpine and Samba versions so you can pin or roll back

The build system produces a family of images rather than one, and the naming convention is the key to using them responsibly. Images are tagged like a3.15.0-s4.15.2, which means a<alpine version>-s<samba version>. The readme is explicit about why: this way you can pin your installation or configuration to a certain version, or easily roll back if you experience problems. That is a versioning scheme with more information in it than a plain latest tag, and it is the difference between a rebuild that changes two layers of your stack and one that does not. Four variants exist. The main one, latest or a<alpine version>-s<samba version>, includes everything, meaning smbd, avahi and wsdd2, and not all of those services need to start, so environment variables are used to disable the optional ones. The smbd-only variant includes smbd and the scripts with neither avahi nor wsdd2 installed at all. The other two are smbd-avahi and smbd-wsdd2, each with one optional service included and still disableable through environment variables. A smaller variant is not only faster to pull, it also has a smaller attack surface, since a daemon that is not installed cannot be misconfigured.

Users and shares are declared as environment variables, including password hashes

Configuration happens through environment variables, and the compose example in the repository shows the shape. The service runs the image ghcr.io/servercontainers/samba, and users are declared with a family of prefixed keys. A group is declared with GROUP_family, and each account gets an ACCOUNT_ entry for the password, a UID_ entry for the numeric id, and GROUPS_ entries naming the groups it belongs to:

    environment:
      MODEL: 'TimeCapsule'
      AVAHI_NAME: StorageServer

      SAMBA_CONF_LOG_LEVEL: 3

      GROUP_family: 1500

      ACCOUNT_alice: alipass
      UID_alice: 1000
      GROUPS_alice: family

      ACCOUNT_bob: bobpass
      UID_bob: 1001
      GROUPS_bob: family

The MODEL variable set to TimeCapsule is what makes the server announce itself in a way Apple clients expect, and AVAHI_NAME sets the name that appears in the zeroconf advertisement. Shares themselves are declared with the SAMBA_VOLUME_CONFIG_ prefix, where the suffix names the share and the value is a Samba share definition. The compose file also shows a hashed password form for accounts, with the comment noting that it is generated using a create-hash.sh script, and a second format using an equals sign between the account name and the hash. Putting plaintext passwords straight into an environment block is the quick path, and the hashed form exists for deployments where the compose file is committed or the environment is inspected by others.

Host networking is the default in the example, and the comment says why that is a risk

The compose example uses host networking, and the file does not pretend that this is free. The comment states that the network_mode setting makes it super easy, especially for zeroconf, but is not as safe as exposing ports directly, and it links a reference on Docker breakout and privilege escalation for host networking. That trade-off is worth understanding before you copy the file. Zeroconf and WSD discovery are link-local broadcast protocols, so a container with published ports on a bridge network may announce itself on the container's network rather than the one your clients are on, and the host mode avoids that. The cost is that the container shares the host's network namespace, which is exactly the arrangement that the linked hardening notes discuss. The same comment also notes that a capability can be added to solve an issue around wsdd2, and that it is not needed for Samba itself, so the extra privilege is scoped to the one optional service that wants it. The rest of the service configuration lives in the environment block, where the optional services can each be switched off with their own variables.

The container runs runit services, and a healthcheck guards the image

The runtime image shows how the services are supervised. The base is Alpine, and the Dockerfile installs runit, tzdata, avahi and samba with apk, then patches the avahi daemon configuration to disable dbus and clears the shipped service files. The environment path is extended so the container's own scripts directory comes first, the repository is copied into the container at /container, and the entrypoint and healthcheck both point into it. The command that starts everything is the runit service directory:

VOLUME ["/shares"]

EXPOSE 137/udp 139 445

HEALTHCHECK CMD ["/container/scripts/docker-healthcheck.sh"]
ENTRYPOINT ["/container/scripts/entrypoint.sh"]

CMD [ "runsvdir","-P", "/container/config/runit" ]

The three exposed ports are the SMB and NetBIOS ones, with 137 as UDP for NetBIOS name service, 139 for NetBIOS session and 445 for SMB over TCP. The volume declaration on /shares is where the data lives. The healthcheck runs a script from the container, which means the orchestrator can tell a working server from a dead one rather than relying on the container staying up. A separate builder stage compiles wsdd2 from source, and the comment in the Dockerfile explains the constraint that shapes it: the upstream Netgear repository was deleted, so the build pulls an immutable tarball from the Debian snapshot archive, and the note warns that the string wsdd2 must be kept on every line of that stage because generate-variants.sh strips the stage out with a grep.

The changelog reads as a history of Apple compatibility problems

The changelog is the most informative document in the repository, and reading it tells you what using this image will feel like. The fruit vfs objects setting has been added, removed and re-added. In August 2025 a warning was issued that a previous statement had been wrong because it broke the fruit configuration, and the setting was removed because people seemed to have more problems with it than it helped, with the advice to restore the old configuration per share instead. In September 2025 the global setting was improved with streams_xattr, described as needed for macOS and iOS integration, and the linked issue was reopened, with a new environment variable DISABLE_FRUIT_DEFAULTS added as a way to turn off the fruit extension entirely. The note about that variable says to use it safely if you do not use these devices. Earlier entries show a fix for filename handling with special characters, the addition of a FAIL_FAST option for errors and conflicts during user and group creation, and a fix for the avahi service configuration. A 2026 entry records a functional smbd test that gates the build, so images only publish if the test passes, and a build.sh option to pick a specific buildx builder.

Where this container is the wrong choice

The limitations are specific and worth weighing. The most cited is UID and GID mapping on Docker Desktop, which the readme flags at the top with a link to an issue. The container manages users by numeric id, and on a Docker Desktop virtual machine the id space on the shared volume does not necessarily match the one on the host, which is exactly the kind of thing that produces files nobody can write. The August 2025 changelog entry about the fruit configuration breaking is a second warning, and it points at the third limitation, which is that the container is tuned for macOS and iOS behaviour and the tuning has caused regressions before. Beyond those, the absence of a licence is a real issue for anything commercial, since the project metadata lists the licence as unknown, and the absence of GitHub releases means there is no versioned artefact beyond the image tags, no changelog entries attached to releases, and no supported upgrade path. The README also points to a TROUBLESHOOTING.md file and an older changelog file for anything not covered in the recent entries, and does not document a rollback procedure for the configuration files the container generates, only for the image version.

Editorial conclusion

ServerContainers samba is a good fit for a home lab or a small team that needs macOS, iOS or Windows clients to reach a Samba share, especially since the tags pair an Alpine version with a Samba version so a deployment can be pinned and rolled back. It is a poor fit for an organisation that needs a supported product, a clear licence, or a container that runs without host networking. Verify first that your clients are happy with the fruit vfs objects configuration the image applies, because the readme links an open issue about UID and GID mapping on Docker Desktop, and check whether the optional discovery services are actually needed before enabling them. The last push was on 2026-07-11 and the repository publishes no GitHub releases.

Frequently asked questions

Official sources

1. Issues
2. README
3. ServerContainers/samba on GitHub