NFS Docker Volumes: Setup and Use

NFS Docker volumes let you mount a Network File System share into a container, so multiple containers across different hosts can read and write the same data as if it were a local folder. You set up the NFS server, then reference the share in a Docker volume definition or directly in a docker run command. This article explains how it works, how to configure it, common pitfalls, and when it makes sense compared to other storage options.

What NFS Docker Volumes Are

Docker volumes are the recommended way to persist data generated by containers. A normal volume lives on the Docker host’s disk. An NFS volume instead points to a directory exported by an NFS server over the network. The container sees it as a local mount point, but the actual bytes are stored on the remote server.

This is useful when you have a cluster of Docker hosts (for example with Docker Swarm) and want a database or file uploads to be accessible from any node. It is also a simple way to share configuration files or media libraries between containers without copying data.

How NFS Volumes Work in Docker

Docker does not implement NFS itself. It relies on the Linux kernel’s NFS client. When you create a volume with an NFS driver, Docker mounts the remote export using the mount system call, just as you would with mount -t nfs. The container then sees the mounted directory at the path you specify.

There are two main ways to use NFS with Docker:

• Legacy --volume syntax – directly in docker run with the nfs driver and options.
• Named volumes – define a volume in docker-compose.yml or via docker volume create with the NFS driver.

Named volumes are cleaner because they are reusable and can be managed with docker volume ls and docker volume inspect.

Setting Up an NFS Server

Before Docker can use NFS, you need a working NFS server. On a typical Linux server (Ubuntu/Debian example):

1. Install the NFS server package: sudo apt install nfs-kernel-server.
2. Create the directory to export, for example /srv/nfs/docker.
3. Add a line to /etc/exports like: /srv/nfs/docker 192.168.1.0/24(rw,sync,no_subtree_check,no_root_squash). The no_root_squash option is often needed so containers running as root can write files with root ownership.
4. Run sudo exportfs -ra to apply the changes.

Make sure the client hosts can reach the server on port 2049 (and possibly the rpcbind port 111). Firewalls between the hosts must allow these ports.

Creating an NFS Docker Volume

Once the server is ready, you can create a named volume. The simplest command is:

docker volume create --driver local \
  --opt type=nfs \
  --opt o=addr=192.168.1.100,rw,nfsvers=4 \
  --opt device=:/srv/nfs/docker \
  nfs-volume

Then use it with docker run -v nfs-volume:/data ....

In docker-compose.yml, the equivalent looks like:

services:
  app:
    image: nginx
    volumes:
      - nfs-volume:/usr/share/nginx/html
volumes:
  nfs-volume:
    driver: local
    driver_opts:
      type: nfs
      o: addr=192.168.1.100,rw,nfsvers=4
      device: ":/srv/nfs/docker"

Note the colon before the path in the device option – that is required by the NFS mount helper.

Common Problems and Troubleshooting

Several issues appear frequently when using NFS with Docker:

• Permission denied – Usually because the exported directory has root_squash enabled, which maps root to nobody. Add no_root_squash to the export options, or run the container with a non-root user that matches the file ownership on the server.
• Mount hangs – Often a network issue or the NFS server is not reachable. Check with showmount -e server_ip from the Docker host.
• NFS version mismatch – Some servers only support NFSv3, while Docker defaults to NFSv4. Specify nfsvers=3 in the o option if needed.
• File locking problems – NFSv3 does not support POSIX locks well. Use NFSv4 if your application requires locking.
• Slow performance – NFS over high-latency links can be slow. Consider tuning rsize and wsize mount options, or using a different storage backend for high I/O workloads.

NFS vs. Other Docker Storage Options

Docker offers several ways to store data. Here is how NFS compares:

• Local volumes – Fastest, but only on one host. Not shared.
• Bind mounts – Map a host directory into the container. Same limitation as local volumes.
• NFS volumes – Shared across hosts, simple to set up, works with any container that can mount NFS. Performance is limited by network.
• Volume plugins (e.g., Ceph, GlusterFS, cloud-specific) – More features (replication, snapshots) but more complex to operate.

For a small cluster or a home lab, NFS is often the easiest shared storage. For production at scale, you might prefer a distributed filesystem or a cloud-managed volume plugin.

Performance and Safety Considerations

NFS performance depends on network speed, latency, and the server’s disk. For workloads that are read-heavy and not latency-sensitive, NFS works well. For databases that require low-latency writes, NFS is usually not recommended because of the network round-trip and potential lock issues.

Safety-wise, NFS does not provide data integrity guarantees beyond what the server’s filesystem offers. If the server crashes, writes that were not flushed may be lost. Use sync export option to reduce this risk, but it slows writes. Always back up the NFS server’s data separately.

Also, be careful with no_root_squash – it gives containers root access to the exported directory, which can be a security risk if containers are untrusted. Only use it when necessary.

Frequently Asked Questions

Can I use NFS volumes with Docker Swarm?

Yes. NFS volumes work with Swarm services as long as the volume is defined in the service’s volumes section. Each node in the Swarm will mount the same NFS share, so containers can be scheduled on any node and still access the same data.

What is the difference between a Docker volume and a bind mount?

A bind mount maps a specific host path (e.g., /home/user/data) into the container. A Docker volume is managed by Docker and stored in its own directory (/var/lib/docker/volumes/). Volumes are easier to back up and move, and they work better with NFS because you can specify the NFS driver directly.

Do I need to install NFS client tools on the Docker host?

Yes. The Docker host must have the NFS client package installed (usually nfs-common on Debian/Ubuntu, nfs-utils on RHEL). Without it, the mount fails with an error like mount.nfs: command not found.

Can I mount an NFS share directly in a container without a named volume?

Yes, you can use the legacy syntax: docker run -v nfs-server:/path:/container/path but this is not recommended because it is less portable and harder to manage. Named volumes are the modern approach.

Is NFS secure over the internet?

NFS was not designed for the public internet. It has no encryption by default and relies on IP-based access control. If you need to access NFS over untrusted networks, use a VPN or SSH tunnel, or use a different storage solution like SSHFS or a cloud object store.

What happens if the NFS server goes down while a container is running?

The container’s mount becomes unavailable. Reads and writes will hang until the server returns, or they may fail with I/O errors. The container itself usually does not crash, but any process accessing the mount will block. Docker will not automatically remount the share; you may need to restart the container once the server is back.

Related

• Hot Water Heater Calculator: Estimate Tank Capacity
• Heat Pump Water Heater Calculator: Estimate Energy Use
• Hot Water Heater GPM Calculator and Sizing Guide