dockur/samba: an SMB file server in a container

What the image provides and what it leaves out

This repository builds a Docker container around Samba, which the README describes as an implementation of the SMB networking protocol. The feature list is short: a lightweight SMB file server, a configurable share name and credentials, multiple users through a list file, read-only and read-write shares, custom Samba configuration, and clients on Windows, macOS and Linux. The image is described as lightweight and Alpine-based.

What it leaves out matters as much as what it includes, and the README is explicit about it in a note. The container only provides the SMB file server and does not run a WS-Discovery service, so the server will normally not appear automatically under Network in Windows.

That is the single most important operational fact in the documentation. Windows File Explorer advertises neighbours over WS-Discovery, and a container that only runs smbd has no such responder, so a user has to type the path. On Windows that is a UNC path such as \\192.168.0.2\Shared, and on macOS or Linux it is an smb:// URL such as smb://192.168.0.2/Shared, with the host IP and the share name substituted.

The second thing it leaves out is anything above the file server. There is no Active Directory join, no domain controller role, no per-group ACL model. The permission system is the flat users file, which is either enough for your use or is not.

The compose file and the docker run equivalent

The compose file at the root of the repository is the whole configuration in one block.

services:
  samba:
    image: dockurr/samba
    container_name: samba
    environment:
      NAME: "Shared"
      USER: "samba"
      PASS: "secret"
    ports:
      - 445:445
    volumes:
      - ./data:/shared
    restart: always

Four decisions are visible there. The image is dockurr/samba, the share is named Shared, the credentials are samba and secret, and the data lives in a bind mount at ./data mapped to /shared in the container. Port 445 is published, which is the standard SMB port, and the restart policy is always.

The Docker CLI form does the same thing in one line.

docker run -it --rm --name samba -p 445:445 -e "NAME=Shared" -e "USER=samba" -e "PASS=secret" -v "${PWD:-.}/data:/shared" docker.io/dockurr/samba

The `${PWD:-.}` fallback in the volume path is a small nicety: it uses the current directory when the shell has a working directory set and falls back to a dot otherwise.

The image on Docker Hub is published under the dockurr organisation, and the badges point at the image size, the pull count and the tags page, which is the usual set of signals for a container that people track versions on.

Ownership, read-only mode and the environment variables

Three environment variables control behaviour that a Samba administrator would otherwise set in the configuration file.

File ownership is automatic by default. The container uses the user and group IDs of the /shared directory, and if either ID is 0, it falls back to 1000 for that value. That fallback exists because a bind mount owned by root would otherwise give Samba a UID of 0, and running the daemon as root is not something you want on a file server. The detected values can be overridden with the UID and GID variables.

environment:
  UID: "1002"
  GID: "1005"

The README says this is useful when the ownership of the mounted directory does not match the IDs you want Samba to use, which is the common case when the host directory is owned by a service account and the container would otherwise guess 1000.

Read-only mode is a single variable.

environment:
  RW: "false"

Setting RW to false changes the Samba share to read-only, which is the switch to reach for when a share is a distribution point rather than a working directory.

The Dockerfile shows the defaults baked in as environment variables, which is a convenient way to see the whole surface: NAME, USER, PASS, RW, UID and GID, with UID and GID set to auto by default rather than to a fixed number.

Multiple users through the users file

Beyond the single USER and PASS pair, the container can be given a list of accounts by bind mounting a users.conf file.

volumes:
  - ./users.conf:/etc/samba/users.conf

Each non-empty line defines one user in a colon separated format.

username:UID:groupname:GID:password:homedir

The README's example shows two accounts sharing a group.

john:1001:users:1001:secret:/shared
jane:1002:users:1001:anothersecret:/shared

The field list in the README is worth reading closely, because two of the fields have constraints that are easy to trip over. The password cannot contain a colon, a newline or a carriage return, which follows from the colon being the field separator. The home directory is optional and defaults to /shared when omitted, which is why the example sets it explicitly and why a line can be as short as username, UID, group, GID and password.

Lines starting with a hash and empty lines are ignored, so a file can carry comments. The example also shows that the primary group is named rather than numeric, with the numeric GID given alongside it, and the two accounts above share the group users with GID 1001 while having different user IDs.

For advanced configuration the same mechanism applies to the main Samba configuration file, where a custom smb.conf is bind mounted over /etc/samba/smb.conf and the default one in the repository can be used as a starting point.

How the image is built and what the healthcheck proves

The Dockerfile is a single stage build on alpine:edge, and the package list is short: tini as the init process, bash, samba itself, tzdata, shadow for the user database and libauth-samba.

Two details in the build are worth noting. The default Samba configuration is removed with rm -f /etc/samba/smb.conf and replaced with the repository's own file copied in as smb.default, so the container's own configuration is generated at startup rather than shipped as the system default. And the script that does that generation, samba.sh, is copied to /usr/bin with mode 755 and becomes the entry point.

The entry point is not the Samba daemon directly.

ENTRYPOINT ["/sbin/tini", "--", "/usr/bin/samba.sh"]

tini is the init process, which reaps the children smbd forks, and samba.sh is the wrapper that reads the environment variables, applies the ownership and writes the effective smb.conf before starting the daemon.

The healthcheck is the most informative line in the file.

HEALTHCHECK --interval=60s --timeout=15s \
    CMD ["smbclient", "--configfile=/etc/samba.conf", "-L", "\\\\localhost", "-U", "%", "-m", "SMB3"]

It lists the shares on localhost with an anonymous login over SMB3, every sixty seconds with a fifteen second timeout. That is a real functional check of the daemon and of the generated configuration, not a check that a process exists, and the SMB3 negotiation in particular confirms that the protocol level is what a modern client would use. The volume declaration for /shared and the exposure of ports 139 and 445 are also in the file, with 445 being the one the compose file publishes.

Where this container is the wrong choice

The first limitation is the missing WS-Discovery service, which the README states outright. The share will not show up in the Windows network browser, and anyone on a network that expects to browse for servers has to be given the path. There is no workaround inside the container, since the service is not running and the image is not designed to add one.

The second is the flat permission model. The users file gives each account a UID, a primary group, a password and a home directory, and that is the whole of it. There are no per-share ACLs, no nested groups, no deny rules. A share that needs different people able to read and different people able to write, per directory, is not something this configuration can express.

The third is the credentials in the environment. The username and password live in environment variables, which in a compose file means a file on disk in plain text, and in a Docker CLI invocation they appear in the shell history. The defaults are samba and secret, so a container started without changing them is an open share on the network with a password everybody knows.

The fourth is the single-purpose scope. This is a file server and nothing else. There is no antivirus, no quotas, no snapshotting, no audit log, and the README does not mention them, so a deployment that expects Samba's full feature set has to look elsewhere. The Alpine base also means the image is small, but it is not a distribution with a security team behind a package repository in the way a full Linux image is.

The fifth is that port 445 is SMB over TCP only in practice, since the image also exposes 139 for NetBIOS. A deployment on a network with a strict firewall policy may find that only the modern path works.

dockur/samba compared with the Samba package and with a NAS appliance

The comparison with installing Samba on the host is the one that determines whether this is worth using. A native install gives you the full smb.conf, the full toolbox including net, testparm and the user database tools, a systemd unit, and a security update path from your distribution. What it does not give you is isolation or reproducibility: the configuration lives on one machine, upgrading Samba is a system operation, and the host is left with a service and an open port.

This container inverts that. The configuration is a compose file, the version is a tag, and the host is left with a directory and a published port. What it gives up is the whole of Samba's surface outside the file server, and the ability to run a service that is not exactly shaped like a Samba share.

A NAS appliance is the third comparison. A commercial NAS gives you a web interface, accounts, disk management, and often a media server and an app package ecosystem on top. The difference in approach is that the NAS is a product with a support contract and a fixed feature set, while this is a building block: you get exactly the file server and you assemble the rest, which for a homelab or a self-hosted setup is often the point and for an enterprise is usually not.

The other angle worth naming is Samba's own container images, and the difference there is control. The dockur images are a set of single service images with an environment variable driven configuration and an Alpine base, which is why they are small and why the configuration surface is as small as it is.

Licence, release cadence and what to check before exposing it

The licence field on the repository records MIT, with the licence file at the root as license.md. A container that ships the Samba binaries carries the terms of both the MIT licence on this repository and the upstream Samba licence, which matters for an organisation that redistributes the image rather than merely running it.

The project is not archived and the last push was on 2026-10-14, the same day as the release. The release history shows a Samba-version-based tagging scheme, with v4.23.10-r0 on 2026-10-14, v4.23.8-r0 on 2026-07-03 and v4.23.7-r0 on 2026-05-21. The -r0 suffix follows the Alpine packaging convention for a rebuild of a given upstream version, so the Samba version and the Alpine release are tracked separately. A rebuild after a Samba security fix appears as a new -r0 tag under the same upstream version, which is a useful thing to be able to see.

Four things to check before this is reachable on a network.

That the default credentials are gone. The image sets USER to samba and PASS to secret, and a share with those is a share with no secret. Whether the port is published beyond the local network. Port 445 is the standard SMB port and it is the one the compose file maps to the host, so exposing it to an untrusted network should be done only after checking encryption and authentication settings.

That the ownership matches the host. With UID and GID left on auto, the container uses the /shared directory's IDs and falls back to 1000 for either ID that is 0, so a directory owned by a service account will get files owned by a numeric id that the person administering the host may not recognise. Set UID and GID explicitly when the host directory has a specific owner.

And that the share name and path are what the users expect, since the client has to be told the path rather than discovering it.

Editorial conclusion

dockur/samba suits someone who needs an SMB share reachable from Windows, macOS and Linux clients without configuring a Samba server on the host, and who is comfortable binding a directory and setting a few environment variables. It is the wrong tool for a team that needs Active Directory integration, a multi-user permission model beyond the flat users file, or a share that appears automatically in the Windows network browser, because the container ships no WS-Discovery service. Before exposing it, change the default credentials, since the image sets the username to samba and the password to secret, and set UID and GID to match the host directory so files do not end up owned by a numeric id nobody can explain.

Frequently asked questions

Official sources

1. dockur/samba on GitHub
2. Issues
3. License: MIT
4. README
5. Releases