Troy's Tech Corner

Transform your Raspberry Pi into a network file server that all your devices can access. Whether you want to centralize family photos, share documents across computers, or create a backup location, a Samba server makes your files accessible from Windows, Mac, and Linux devices seamlessly.

Prerequisites

Before starting, make sure you have:

Raspberry Pi with Docker installed (from our Docker guide)
External storage (USB drive or external HDD) - optional but recommended
Basic knowledge of Docker and Docker Compose
Your Pi accessible on your network

Why Use Samba?

Samba implements the SMB/CIFS protocol, which is the standard file sharing protocol for Windows networks. Benefits include:

Universal compatibility: Works with Windows, Mac, Linux, and even mobile devices
Easy to use: Appears as a network drive in your file explorer
No special client software: Built into every major operating system
Good performance: Suitable for streaming media and large file transfers
Flexible permissions: Control who can access what

Planning Your File Server

Before we begin, decide on:

Storage location: Will you use the SD card, a USB drive, or an external hard drive? For anything beyond testing, use external storage.

Share structure: What folders do you want to share? Common setups include:

Media (movies, music, photos)
Documents
Backups
Software/ISOs
Personal folders for each family member

Access control: Will everyone have full access, or do you need per-user permissions?

Step 1: Prepare Your Storage

If you're using an external drive, let's set it up properly.

Connect your drive to your Raspberry Pi and identify it:

lsblk

You'll see output like:

NAME        MAJ:MIN RM   SIZE RO TYPE MOUNTPOINT
sda           8:0    0 931.5G  0 disk
└─sda1        8:1    0 931.5G  0 part

Your drive is likely /dev/sda1 (or similar).

Create a mount point:

sudo mkdir -p /mnt/storage

Format the drive (if new - this erases all data):

sudo mkfs.ext4 /dev/sda1

Get the drive's UUID:

sudo blkid /dev/sda1

Note the UUID value (looks like: 12345678-1234-1234-1234-123456789abc)

Set up automatic mounting:

sudo nano /etc/fstab

Add this line at the bottom (replace UUID with yours):

UUID=your-uuid-here /mnt/storage ext4 defaults,nofail 0 2

Mount the drive:

sudo mount -a

Verify it's mounted:

df -h | grep storage

Step 2: Create Directory Structure

Let's create a logical folder structure:

sudo mkdir -p /mnt/storage/{media,documents,backups,public}
sudo mkdir -p /mnt/storage/media/{movies,tv,music,photos}

Set ownership so Docker can access these folders:

sudo chown -R $USER:$USER /mnt/storage
sudo chmod -R 775 /mnt/storage

Step 3: Set Up Samba with Docker

Create a directory for your Samba configuration:

mkdir -p ~/docker/samba
cd ~/docker/samba

Create a docker-compose.yml file:

nano docker-compose.yml

Add this configuration:

version: '3.8'

services:
  samba:
    image: dperson/samba
    container_name: samba
    restart: unless-stopped
    ports:
      - "139:139"
      - "445:445"
    volumes:
      - /mnt/storage:/mount
    environment:
      - TZ=America/New_York
      - USERID=1000
      - GROUPID=1000
    command: >
      -s "Public;/mount/public;yes;no;no;all;none"
      -s "Media;/mount/media;yes;no;no;all;none"
      -s "Documents;/mount/documents;yes;no;no;all;none"
      -s "Backups;/mount/backups;yes;no;no;all;none"
      -u "youruser;yourpassword"
      -w "WORKGROUP"

Understanding the configuration:

Ports:

139: NetBIOS session service
445: SMB file sharing

Environment variables:

TZ: Your timezone
USERID and GROUPID: Match your user (find with id command)

Command parameters: Each -s creates a share with this format:

-s "ShareName;/path;browseable;readonly;guest;users;admins"
- ShareName: Name that appears in network browser
- /path: Path inside container
- browseable: yes/no - appears in network listing
- readonly: yes/no - write protection
- guest: yes/no - allow anonymous access
- users: comma-separated list of users with access (or "all")
- admins: comma-separated list of admin users (or "none")

User creation:

-u "username;password" creates a Samba user

Workgroup:

-w "WORKGROUP" sets the Windows workgroup name

Step 4: Customize for Your Needs

Adjust the timezone to match your location:

- TZ=America/Los_Angeles  # Change this

Change the username and password:

-u "john;SecurePassword123"

Get your user and group IDs:

id

Update USERID and GROUPID in the compose file to match.

Step 5: Deploy the Samba Server

Start the container:

docker-compose up -d

Check if it's running:

docker-compose logs

You should see messages indicating Samba is starting and shares are being created.

Step 6: Connect from Windows

Open File Explorer and in the address bar type:

\\your-pi-ip-address

For example: \\192.168.1.100

You'll see your shares listed. Double-click one to open it.

Enter credentials when prompted:

Username: The username you set in docker-compose
Password: The password you set

Map a network drive for quick access:

Right-click on "This PC"
Choose "Map network drive"
Select a drive letter
Enter: \\192.168.1.100\Media (or your share name)
Check "Reconnect at sign-in"
Enter credentials if prompted

Step 7: Connect from Mac

Open Finder and press Cmd+K (or Go → Connect to Server)

Enter:

smb://your-pi-ip-address

For example: smb://192.168.1.100

Click Connect and enter your username and password.

Mount at startup:

Open System Preferences → Users & Groups
Select your user → Login Items
Drag the mounted share from desktop to the list

Step 8: Connect from Linux

Using the file manager:

Most Linux file managers support SMB. In the file manager, look for "Connect to Server" or similar.

Enter: smb://192.168.1.100/Media

Mounting via command line:

Install cifs-utils:

sudo apt install cifs-utils

Create a mount point:

sudo mkdir /mnt/pi-media

Mount the share:

sudo mount -t cifs //192.168.1.100/Media /mnt/pi-media -o username=youruser,password=yourpass

Mount automatically at boot:

Create a credentials file:

sudo nano /root/.smbcredentials

Add:

username=youruser
password=yourpassword

Secure it:

sudo chmod 600 /root/.smbcredentials

Add to /etc/fstab:

//192.168.1.100/Media /mnt/pi-media cifs credentials=/root/.smbcredentials 0 0

Step 9: Adding User Authentication

For better security, let's set up individual user accounts. Update your docker-compose.yml:

    command: >
      -s "Public;/mount/public;yes;no;yes;all;none"
      -s "Media;/mount/media;yes;no;no;alice,bob;none"
      -s "AlicePrivate;/mount/users/alice;yes;no;no;alice;alice"
      -s "BobPrivate;/mount/users/bob;yes;no;no;bob;bob"
      -u "alice;AlicePassword123"
      -u "bob;BobPassword456"
      -w "WORKGROUP"

Create user directories:

sudo mkdir -p /mnt/storage/users/{alice,bob}
sudo chmod 700 /mnt/storage/users/*

Restart the container:

docker-compose down
docker-compose up -d

Now Alice and Bob each have private folders plus shared access to Media.

Step 10: Performance Optimization

Add these options to your compose file for better performance:

    command: >
      -s "Media;/mount/media;yes;no;no;all;none;Media share"
      -g "socket options = TCP_NODELAY IPTOS_LOWDELAY SO_RCVBUF=524288 SO_SNDBUF=524288"
      -g "read raw = yes"
      -g "write raw = yes"
      -g "min receivefile size = 16384"
      -g "use sendfile = yes"
      -g "aio read size = 16384"
      -g "aio write size = 16384"
      -u "youruser;yourpassword"
      -w "WORKGROUP"

These settings optimize TCP buffer sizes and enable asynchronous I/O for better throughput.

Advanced Configuration: Read-Only and Guest Shares

Create a read-only share for archived content:

-s "Archive;/mount/archive;yes;yes;no;all;none"

Create a guest-accessible share (no password required):

-s "GuestShare;/mount/public;yes;no;yes;all;none"

Guest access means anyone on your network can access without credentials. Use carefully.

Monitoring and Maintenance

Check disk usage:

df -h /mnt/storage

View active connections:

docker exec samba smbstatus

View container logs:

docker-compose logs -f

Restart the server:

docker-compose restart

Backing Up Your Configuration

Save your setup by backing up:

# Backup compose file
cp ~/docker/samba/docker-compose.yml ~/docker/samba/docker-compose.yml.backup

# Or better yet, use git
cd ~/docker/samba
git init
git add docker-compose.yml
git commit -m "Initial Samba configuration"

Troubleshooting Common Issues

Can't connect from Windows:

Verify SMB1 isn't required (it's insecure and disabled by default in Windows 10/11)
Check Windows Firewall isn't blocking ports 139/445
Try using IP address instead of hostname
Ensure Network Discovery is enabled in Windows

Can't connect from Mac:

Check macOS Firewall settings
Try smb:// instead of cifs://
Verify you're using the correct username/password

Permission denied errors:

Check USERID and GROUPID match your user
Verify folder permissions on the host: ls -la /mnt/storage
Ensure the user exists in Samba: -u "username;password"

Slow transfer speeds:

Check if your USB drive is USB 3.0 (not 2.0)
Verify the drive is formatted as ext4, not NTFS (slower)
Try the performance optimizations mentioned above
Check network connection (use Ethernet, not WiFi if possible)

Container won't start:

Check logs: docker-compose logs
Verify no other service is using ports 139 or 445
Ensure mount path /mnt/storage exists and is accessible

Security Best Practices

Use strong passwords: Each user should have a unique, strong password.

Don't expose to the internet: Samba should only be accessible on your local network. If you need remote access, use a VPN.

Regular updates: Keep your Docker image updated:

docker-compose pull
docker-compose up -d

Limit guest access: Only use guest shares for truly public content.

Set up firewall rules: If your Pi has UFW installed:

sudo ufw allow from 192.168.1.0/24 to any port 445
sudo ufw allow from 192.168.1.0/24 to any port 139

This limits Samba access to your local network only.

Expanding Your File Server

Add Time Machine support for Mac backups:

-s "TimeMachine;/mount/timemachine;yes;no;no;alice;alice;Alice backup"
-g "fruit:time machine = yes"

Add recycle bin functionality:

-s "Media;/mount/media;yes;no;no;all;none"
-g "vfs objects = recycle"
-g "recycle:repository = .recycle"
-g "recycle:keeptree = yes"
-g "recycle:versions = yes"

Deleted files go to a .recycle folder instead of being permanently deleted.

Next Steps

Your file server is now the central storage hub for your home network. Consider these next projects:

Set up automated backups - Use rsync or another backup solution to protect your data
Deploy a media server - Install Plex or Jellyfin to stream your media collection
Add network monitoring - Track bandwidth usage and connection statistics
Create a photo gallery - Use PhotoPrism or Immich to organize family photos
Set up cloud sync - Use Nextcloud to sync files across devices

Quick Reference

Restart Samba:

cd ~/docker/samba
docker-compose restart

View logs:

docker-compose logs -f

Add a new user: Edit docker-compose.yml and add:

-u "newuser;newpassword"

Then: docker-compose up -d

Add a new share: Add to command section:

-s "NewShare;/mount/newshare;yes;no;no;all;none"