Convert an existing Samba server to Docker

Samba on Docker

This is a quick "how to" guide to convert an existing Samba (smbd) server to Docker.

Why run Samba on Docker?

  • Version choice: In my case, I want to run Samba version 4.8, which is not available by default on Ubuntu 18.04. Version 4.8 or higher is needed to support backups using Apple's Time Machine.
  • Version stability: Related to the above, Docker separates the version of a service from that of the host's package manager.
  • Portability. By encapsulating a service inside a container, and keeping any persistent data in known locations within a directory, moving Samba from one machine to another is simple.
  • Security. Samba within a container can only access the paths on the host explicitly mapped to it in the configuration file, and access to the host is reduced. This improves security and reduces the impact of any security issue in Samba itself.

Problems with a stateless approach

The current top hit on Google for "docker samba" is the dperson/samba repository on Github. This looks interesting, and even provides a Docker Compose file, which makes starting and stopping the service easy. Why not just use that?

The dperson/samba repository takes what you might call a stateless approach. The configuration is entirely specified within the Docker file. There are a few disadvantages to this approach:

  • Passwords are stored in plain text, either on the command line or in a Docker Compose file
  • Moving from an existing Samba installation to dperson/samba would require the existing configuration and password database to be converted manually.

Another approach: preserve existing configuration

Since I wanted to port an existing Samba server, I created a Docker Compose configuration that utilises the existing /etc/samba/smb.conf configuration file, and /var/lib/samba, which contains Samba's password database, i.e. this is a stateful approach. This has pros and cons:


  • You can easily port an existing Samba server to Docker
  • You can easily move back and forth between Docker and native (non-Docker) Samba
  • You use the smb.conf file format, and smbpasswd and friends. Good if you're already familiar with Samba administration.


  • The container requires read-only access to your /etc/passwd and /etc/shadow files, which is a very small increased security risk version the dperson/samba approach: in the unlikely event an attacker gained access to the file system within the Docker container, they would have a list of all your accounts instead of just those associated with Samba. Passwords in /etc/shadow are encrypted, so to my mind this risk is small and acceptable (and certainly less than running Samba outside of Docker).
  • Requires an existing Samba installation. If you are starting from scratch and are only planning on a small number of shares and users, the dperson/samba repository might be a better fit.

My approach is based on the dperson/samba repository, with some modifications.

The Dockerfile installs Samba on Alpine Linux, which keeps the size small, but also uses a relatively up to date version (4.8 at the time of writing), which will allow us to use Apple's Time Machine.

OK, how do I perform the conversion?

Before you start, you'll need an existing, working Samba installation on the host machine. I'll assume the configuration is in /etc/samba and the library files are in /var/lib/samba, which are the defaults on Ubuntu. You can update those paths in the docker-compose.yml file if needed.

1. Download the configuration, which is simply a Dockerfile and a docker-compose.yml file:

git clone

You could also download or copy/paste those files manually from the GitHub URL, if you prefer.

2. Add your Samba shares to the volumes section of docker-compose.yml file, e.g.:

- /home/alex/share1:/home/alex/share1
- /home/alex/share2:/home/alex/share2:ro

The :ro flag on the end makes the share read only (this probably ideally match what's specified in your smb.conf). You could also update your timezone using on the TZ: line in the Compose file, if you like.

3. Stop any existing Samba service on the host. On Ubuntu and most recent Linux systems, that's sudo systemctl stop smbd, and sudo systemctl disable smbd to stop it coming back on reboot.

4. Build and start the Docker Samba container with docker-compose up -d --build.

That's all there is to it. If you prefer to keep everything in one directory, you could move or copy /etc/samba to ./config and /var/lib/samba to ./lib. This makes it easier to backup or transfer to other machines, since the Samba configuration is all in one directory. The configuration files are pretty simple, so feel free to reuse or adapt as needed.

Thanks for reading!

Related Posts