Why a Docker‑Based Home NAS?
If you’re looking to turn a spare PC, a Raspberry Pi, or an old laptop into a file server that talks to Windows, macOS, and Linux, Docker is a great way to keep the host clean. You can drop in or pull out services without messing with the kernel, and you still get the familiar NFS/SMB combo that covers every client. Below is a walk‑through that sticks to Debian 12 or Ubuntu 24.04, but the same ideas work on any distro with systemd and Docker.
1. Hardware & OS
| Component | Recommendation | Why |
|---|---|---|
| CPU | 2‑core ARM or x86‑64 (Pi 4, NUC, or a spare desktop) | SMB/NFS + light Docker won’t break anything |
| RAM | 2 GB min, 4 GB better | Containers share memory; 4 GB keeps headroom |
| Storage | 1 TB SSD/NVMe or a 2‑bay NAS enclosure | SSD gives snappier I/O; NVMe is a bonus for media |
| Network | Gigabit Ethernet | SMB/NFS thrive on 1 Gbps; 2.5 GbE is overkill for most homes |
Install a minimal Debian or Ubuntu server. Enable SSH and set a strong key or password during setup. Keep the system up‑to‑date:
sudo apt update && sudo apt upgrade -y
sudo apt install -y curl gnupg
2. Docker on the Host
Debian/Ubuntu ship Docker, but the upstream engine is newer. I usually run the official install script:
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
Add yourself to the docker group so you can run containers without sudo:
sudo usermod -aG docker $USER
newgrp docker
Verify with a quick test:
docker run --rm hello-world
You should see the “Hello from Docker” message.
3. Persistent Storage
Create a mount point for the NAS data. If you have a dedicated SSD, mount it at /mnt/nas. For a single‑disk box, just use a subdirectory:
sudo mkdir -p /mnt/nas
sudo chown -R $USER:$USER /mnt/nas
Docker volumes live under /mnt/nas/docker-volumes. Create the one we’ll use:
docker volume create --name nas-data
That volume backs /mnt/nas/docker-volumes/nas-data, keeping data outside the container filesystem.
4. NFS Service in Docker
4.1. Use the official image
We’ll pull itsthenetwork/nfs-server-alpine. It’s tiny and already wired for Docker, so no Dockerfile needed.
4.2. Spin it up
docker run -d \
--name nas-nfs \
--restart unless-stopped \
-p 2049:2049/tcp -p 111:111/tcp \
-v nas-data:/exports \
-e SHARED_DIRECTORY=/exports \
-e ALLOW_ROOT_ACCESS=true \
itsthenetwork/nfs-server-alpine
-p 2049– NFS data-p 111– portmapper-v nas-data:/exports– mount the Docker volumeALLOW_ROOT_ACCESS=true– lets root on clients; remove if you want stricter security
4.3. Check the export
On the host:
sudo nfsstat -s
You should see /exports listed. On a Linux client:
sudo mount -t nfs4 <NAS_IP>:/exports /mnt/nas
If you hit “Permission denied”, look inside the container at /etc/exports. The image auto‑generates *(rw,sync,no_subtree_check), which is fine for a home network.
5. SMB Service in Docker
5.1. Docker Compose file
Create /opt/nas/docker-compose.yml:
version: "3.8"
services:
nas-smb:
image: dperson/samba
container_name: nas-smb
restart: unless-stopped
ports:
- "139:139"
- "445:445"
volumes:
- nas-data:/srv/samba
environment:
- USERID=1000
- GROUPID=1000
- SHARE=nas
- SHARE_PATH=/srv/samba
- SHARE_READONLY=false
- SHARE_WIKIPAGE=Home NAS
- SHARE_COMMENT=Shared folder for all devices
- SHARE_PERMISSIONS=0777
dperson/samba is minimal and reliable. The env vars create a single share called nas.
5.2. Start it
cd /opt/nas
sudo docker compose up -d
5.3. Set a real password
The container comes with smbuser:smbpass by default. Change it:
sudo docker exec nas-smb smbpasswd -a smbuser
Enter a new password when prompted.
5.4. Connect from the clients
Windows
- Open File Explorer.
- Type
\\<NAS_IP>\nas. - Log in with
smbuserand the new password.
macOS
open smb://smbuser:<password>@<NAS_IP>/nas
Linux
sudo mount -t cifs //<NAS_IP>/nas /mnt/nas \
-o username=smbuser,password=<password>,rw
6. Client Configuration
| OS | Mount command | Notes |
|---|---|---|
| Linux | sudo mount -t nfs4 <NAS_IP>:/exports /mnt/nas |
Add to /etc/fstab for persistence. |
| Windows | \\<NAS_IP>\nas |
Use SMB credentials. |
| macOS | open smb://smbuser:<password>@<NAS_IP>/nas |
Add to Finder “Connect to Server”. |
6.1. fstab entry (Linux)
<NAS_IP>:/exports /mnt/nas nfs4 defaults,auto,nofail,vers=4.1 0 0
6.2. SMB fstab (Linux)
//<NAS_IP>/nas /mnt/nas cifs credentials=/etc/samba/creds,iocharset=utf8,uid=1000,gid=1000,file_mode=0777,dir_mode=0777 0 0
Create /etc/samba/creds:
echo "username=smbuser" | sudo tee /etc/samba/creds
echo "password=<password>" | sudo tee -a /etc/samba/creds
sudo chmod 600 /etc/samba/creds
7. Security & Best Practices
| Area | Recommendation | Why |
|---|---|---|
| Network isolation | Put the NAS on a separate VLAN or subnet | Keeps it out of the way of other traffic |
| Firewall | Allow only 2049, 111, 139, 445 from trusted IPs | Cuts the attack surface |
| Samba user | Use a dedicated user with a strong password | Avoids using system accounts |
| NFS export | Stick with root_squash unless you really need root |
Safer by default |
| Docker updates | docker pull itsthenetwork/nfs-server-alpine and docker pull dperson/samba regularly |
Keeps services patched |
| Backups | Snapshot the Docker volume or rsync to another drive | Protects against accidental deletes |
8. Troubleshooting Common Issues
| Symptom | Likely Cause | Fix |
|---|---|---|
| NFS mount fails with “Permission denied” | Wrong export options or missing rpcbind |
Make sure -p 111 is exposed; check /etc/exports inside container |
| SMB login fails | Wrong password or user not created | Re‑run smbpasswd -a smbuser inside container |
| Clients can’t see the share | Firewall blocking ports | Open 139/445 on the host (ufw allow 139/tcp, ufw allow 445/tcp) |
| Container crashes on start | Port conflict | Verify no other service uses 2049, 139, or 445 |
| Data disappears after container restart | Volume not mounted correctly | Check docker volume inspect nas-data and confirm -v nas-data:/exports is present |
9. Scaling Up
If you want to add Nextcloud, Plex, or something else, just drop a new service into the same Compose file or create a separate stack. Keep the data volume separate so you can swap out services without moving the data:
services:
plex:
image: plexinc/pms-docker
volumes:
- nas-data:/data
The same nas-data volume can be shared across containers, but remember to adjust file permissions inside the container to match the host UID/GID.
10. Final Thoughts
A Docker‑based NAS gives you:
- Isolation – each service runs in its own container.
- Portability – move the Docker volume to another host if needed.
- Simplicity – no need to install NFS/SMB packages on the host.
The overhead is minimal on a modern home server, and the ability to upgrade or replace a service without touching the host OS is a huge win.
Happy file sharing!
See also
- Running a Rootless Podman Web App with Persistent Volumes on Ubuntu
- Why My Home Assistant Timer Never Fires—and How to Fix It
- Fixing a Broken /etc/hosts When systemd‑resolved Hides It
- Running a Self‑Hosted GitLab CI Runner on a Raspberry Pi 4
- Rootless Docker‑Compatible Service on a Home Server: Step‑by‑Step Guide