DevOps/Docker/Mount remote storage to container.md

Mount remote storage to container using compose file

(https://oneuptime.com/blog/post/2025-12-15-how-to-use-nas-storage-with-docker-compose/view)

There are 3 types of remote connections possible, NFS, CIFS and iSCSI.

In addition to having the containers connect directly to the remote storage, it is also possible to simply let the host mount a remote storage location to a local mount point and then point the container to this location on the local host.

Quick Protocol Comparison

Protocol	Best For	Strengths	Watch-outs
NFS	Linux hosts, shared access across containers	Simple setup, low overhead, native Docker support	No built-in encryption, UID/GID mapping can be tricky
SMB/CIFS	Windows hosts, mixed environments, AD integration	Works everywhere, credential-based auth	Higher overhead, requires cifs-utils on host
iSCSI	Containers that need block access to storage
Local mount + bind	Maximum performance, simple setups	No network latency, works offline	Requires NAS mounted on host first

Prerequisites

Before starting:

• Your NAS is reachable from your Docker host (same network or routed)
• You have created a share/export on your NAS
• Your Docker host has the required client packages

Installing Required Packages

For NFS on Debian/Ubuntu:

The NFS client package allows your Docker host to mount NFS shares. This is a one-time setup required before Docker can create NFS volumes.

# Update package list and install NFS client utilities
# nfs-common includes mount.nfs required for NFS volume mounts
sudo apt-get update && sudo apt-get install -y nfs-common

For NFS on RHEL/Rocky/AlmaLinux:

# Install NFS utilities for Red Hat-based distributions
# Includes rpcbind and other NFS dependencies
sudo dnf install -y nfs-utils

For SMB/CIFS:

CIFS utilities are required when connecting to Windows shares or NAS devices configured for SMB protocol.

# Debian/Ubuntu - install CIFS mount utilities
sudo apt-get install -y cifs-utils

# RHEL/Rocky - same package, different package manager
sudo dnf install -y cifs-utils

NFS

This Docker Compose configuration demonstrates how to declare an NFS volume using the built-in local driver with NFS options. The volume is mounted into the container just like any other Docker volume.

Example 1:

# docker-compose.yml
version: "3.8"

services:
  app:
    image: nginx:alpine
    volumes:
      # Mount the NFS volume to serve static files
      - nfs-data:/usr/share/nginx/html
    ports:
      - "8080:80"

# Volume definitions - NFS configuration lives here
volumes:
  nfs-data:
    # Use the local driver with NFS-specific options
    driver: local
    driver_opts:
      # Specify NFS as the filesystem type
      type: nfs
      # Mount options: NAS IP, NFS version, and behavior flags
      # soft = return errors on timeout, nolock = disable file locking
      o: addr=192.168.1.100,nfsvers=4.1,soft,nolock
      # NFS export path on your NAS (note the leading colon)
      device: ":/volume1/docker-data"

Example 2:

volumes:
  # Database volume: use 'hard' mount for data integrity
  # 'hard' = retry indefinitely on failure (prevents data corruption)
  # 'intr' = allow interrupt to prevent hung processes
  postgres-data:
    driver: local
    driver_opts:
      type: nfs
      o: addr=192.168.1.100,nfsvers=4.1,hard,intr
      device: ":/volume1/docker/postgres"

NFS Mount Options Explained

Option	Purpose
addr=	NAS IP address
nfsvers=4.1	NFS version (use 4.1 or 4.2 for best compatibility)
soft	Return errors on timeout instead of hanging (use hard for databases)
nolock	Disable file locking (faster, but don't use for databases)
rw	Read-write mount (default)
noatime	Don't update access times (better performance)

CIFS

For Windows environments or when your NAS only offers SMB shares.

Basic SMB Volume

version: "3.8"

services:
  app:
    image: nginx:alpine
    volumes:
      - smb-data:/usr/share/nginx/html

volumes:
  smb-data:
    driver: local
    driver_opts:
      type: cifs
      o: addr=192.168.1.100,username=myuser,password=mypassword,file_mode=0777,dir_mode=0777
      device: "//192.168.1.100/docker-data"

SMB with Credentials File (More Secure)

Storing passwords in docker-compose.yml is a bad idea. Use a credentials file instead:

# Create credentials file on Docker host
sudo nano /etc/docker-smb-credentials

username=myuser
password=mypassword
domain=WORKGROUP

sudo chmod 600 /etc/docker-smb-credentials

version: "3.8"

services:
  app:
    image: nginx:alpine
    volumes:
      - smb-data:/usr/share/nginx/html

volumes:
  smb-data:
    driver: local
    driver_opts:
      type: cifs
      o: addr=192.168.1.100,credentials=/etc/docker-smb-credentials,uid=1000,gid=1000,file_mode=0644,dir_mode=0755
      device: "//192.168.1.100/docker-data"

SMB Mount Options

Option	Purpose
credentials=	Path to credentials file
uid= / gid=	Map files to specific user/group ID
file_mode= / dir_mode=	Set permissions for files/directories
vers=3.0	SMB protocol version (try 2.1 or 3.0)
seal	Enable encryption (SMB 3.0+)

iSCSI

Example:

version: "3"

services:
  app:
    image: your-image
    volumes:
      - myiscsi:/data

volumes:
  myiscsi:
    driver: local
    driver_opts:
      type: iscsi
      device: "iqn.2025-10.com.example:storage"
      o: "addr=192.168.1.100"