jord4ncodes/timemachine repository overview

⁠Time Machine Samba Server

Repository: https://github.com/4lbertojordan/timemachine⁠

A simple Docker-based Samba server optimized for macOS Time Machine backups. Provides a reliable and secure Time Machine destination for local network backups.

⁠Features

• Debian-based lightweight image
• Samba 4 with SMB2/SMB3 protocol support
• Apple Time Machine optimized configuration
• User/password authentication
• Healthcheck included
• Multi-architecture support (amd64, arm64)

⁠Requirements

• Docker and Docker Compose installed
• Port 445/tcp available
• ARM64 or x86-64 architecture
• Host storage for Time Machine backups (I recommend using an external drive or NAS isolated from the OS)

⁠Supported macOS Versions

Time Machine backups are compatible with MacOS:

• Tested and working on macOS Tahoe 26.2 (25C56)

⁠Quick Start

⁠1. Create Environment File and Set Permissions

Create .env.timemachine in your repository root: (You can copy from variables_file_example.txt in this repo)

# Samba user and password
SMB_USER=backup_user_here
SMB_PASSWORD=your_secure_password_here
SMB_UID=1000
SMB_GROUP=home
SMB_GID=1000

# Container timezone
TZ=Europe/Madrid

Set permission for time machine directory:

mkdir -p ./timemachine
chown 1000:1000 ./timemachine && chmod 700 ./timemachine

⁠2. Launch the Container

docker compose -p timemachine -f docker-compose.yml up -d

⁠3. Configure Time Machine on macOS

This Time Machine share is automatically discovered using Avahi (Bonjour) if not please follow these steps:

1. Open your terminal and run:

   sudo tmutil setdestination -p "smb://jordancodes@YOUR_SERVER_IP/TimeMachine"
   

   Copy

2. Enter your Samba password when prompted.

3. Open System Settings → General → Time Machine and ensure the Time Machine share is selected.

4. Start your first backup!

⁠Configuration

⁠Environment Variables

⁠Samba Configuration

The server configuration is defined in timemachine/smb_timemachine.conf⁠.

Key Settings:

• Time Machine Volume: /timemachine (inside container)
• Share Name: [TimeMachine]
• Protocol: SMB2/SMB3
• Security Model: User authentication required
• Mac Optimization: Enabled with fruit:time machine = yes
• Max Backup Size: 850GB (configurable)

Network Security:

I recommend allowing only trusted networks:

• 127.0.0.1 (localhost)
• 192.168.XXX.0/24 (local network example - adjust to your network)
• 10.8.0.0/24 (VPN network example - adjust to your VPN)

⁠Troubleshooting

⁠Cannot Connect from macOS

Check if Samba is running:

docker compose -p timemachine -f docker-compose.yml ps

Verify port is listening:

netstat -an | grep 445

Check Samba logs:

docker logs timemachine

⁠Authentication Issues

Ensure credentials match .env.timemachine:

• Username must match SMB_USER
• Password must match SMB_PASSWORD

⁠Slow Backups

• Check network connection (use wired ethernet if possible)
• Verify no other heavy network activity
• Check available disk space
• Consider increasing memory limit in docker-compose.yml

⁠Permission Errors

Ensure the timemachine directory has proper permissions:

# linux host
ls -la ./timemachine/
# Should be owned by the user running Docker

⁠macOS Exclusions

You can exclude folders from Time Machine backups:

1. Open System Settings → General → Time Machine
2. Click Options
3. Add folders to exclude list

⁠Monitoring Backups

⁠Check Backup Status on macOS

NOTE: I detect that tmutil commands may require some time to reflect any information.

# Show latest backup
tmutil latestbackup

# List all backups
tmutil listbackups

# Check backup size
tmutil calculatedrift