Docker Samba Time Machine Server

A Samba server tailored for macOS Time Machine backups, running on Debian (Trixie) inside a Docker container.

This project was inspired by the guide: Ultimativer Leitfaden: Samba für Time-Machine-Backups auf Debian-Servern einrichten.

Key Features

• macOS Native Support: Uses vfs_fruit for enhanced compatibility and performance with macOS.
• Time Machine Ready: Pre-configured with all necessary settings for macOS to recognize it as a backup destination.
• Secure User Management: Passwords are stored as NT hashes, not plaintext.
• Flexible Storage: Supports mounting physical disks by UUID or device path, or using standard Docker volumes.
• ZeroConf / Bonjour: Works out-of-the-box with macOS network discovery (mDNS) thanks to host networking mode.
• Resource Limits: Optional fruit:time machine max size to prevent backups from filling your entire disk.

Prerequisites

• Docker Engine 20.10+
• Docker Compose (v2)
• A Linux host (required for network_mode: host and systemd integration)

Quick Start

1. Initial Setup

Clone the repository and prepare your environment file:

cp env.example .env

Edit the .env file to match your setup. You can choose between mounting a physical disk (recommended) or using a local directory.

2. Configure Users

Use the interactive script to create or update users. This script generates the required NT hashes for Samba:

./setup-users.sh

This will update templates/users.txt with the hashed credentials.

3. Launch the Server

Start the container using Docker Compose:

docker compose up -d

Configuration Options (.env)

Variable	Description	Default
SAMBA_DEVICE_UUID	UUID of the disk to mount (e.g., from lsblk -o +UUID)	None
SAMBA_DEVICE	Path to the device to mount (e.g., /dev/sdb1)	None
SAMBA_VOLUME	Host path for backups (if not using physical disk)	./data
SAMBA_SHARE_NAME	The name of the share as seen by macOS	TimeMachine
SAMBA_TIME_MACHINE_MAX_SIZE	Maximum size for backups (e.g., 500G, 1T)	0 (unlimited)
TZ	Timezone (e.g., Europe/Berlin)	Host detection

Connecting from macOS

1. Open Finder.
2. Press Cmd + K or select Go > Connect to Server....
3. Enter smb://<your-server-ip>.
4. Log in with the credentials you created earlier.
5. Open System Settings > General > Time Machine.
6. Click Add Backup Disk... and select your Samba share.

Technical Details

• Host Networking: The container uses network_mode: host to allow Samba to broadcast discovery packets (mDNS/Bonjour) so the Mac can find it automatically in the sidebar. Note: Ensure your host firewall allows traffic on the standard Samba ports (TCP 445, TCP 139, UDP 137, UDP 138) and the mDNS port (UDP 5353).
• ZeroConf / Bonjour: Samba handles discovery internally. However, this can conflict with an existing avahi-daemon on the host. Depending on your Linux distribution:
  • Recommended: Remove avahi-daemon from the host (sudo apt remove avahi-daemon) to allow the container's discovery to work natively.
  • Alternative: If shares do not appear after removal, some setups (like older Debian) may actually require Avahi to be running. If you keep Avahi, ensure it doesn't interfere with the container's mDNS broadcasts.
• Systemd: The container runs a minimal systemd init system to manage smbd and nmbd properly.
• Privileged Mode: Required if you choose to mount physical disks directly within the container context.

License

This project is licensed under the GPLv3 License.