How to Mount an NFS Share Into a Container

This post will show you how to mount an NFS share into a container. We will explore mounting an NFS to the container via Portainer and Docker Compose. It is truly super easy to do!

Off course! You can mount your NFS to the host, and then mount the host’s NFS folder into the container. But, this method can be avoided. Mounting the NFS directly to the container avoids a manual NFS mount on the host and/or using the /etc/fstab.

Adding an NFS drive requires you to create a Volume. Volumes simply reference files and folders on the host, or (in this case) a Network File System (or NFS for short).

Create an NFS Volume Using Portainer

Click on the ‘Volumes’ menu item and the ‘Add Volume’ button.

Portainer, Volumes, Add Volume
Portainer, Volumes, Add Volume

Next, you need to specify the following options:

  • The name of the NFS volume you want to use in the container.
  • The driver configuration must be set to ‘local’.
  • Tick the ‘NFS’ volume radio button.

In the NFS settings section, set the:

  • address of the NFS server you wish to use. You can use a DNS name or IP address.
  • NFS version can be set to ‘NFS’ or ‘NFS4’. When in doubt use ‘NFS’.
  • Mount point on your NFS server.
  • Set the various option that applies to your implementation.

Lastly, click the ‘Create the volume’ button for the NFS volume to be added.

Portainer, Volumes, Create Volume
Portainer, Volumes, Create Volume

You can now reference your NFS volume using the volume name you specified. See the example in the Docker Compose section below for an example.

Create an NFS Volume Using Docker Compose

You can also use Docker Compose to specify an NFS volume to mount into the container. The example below configures a MySQL container and the mounts the ‘nfs-mysql-vol’ to the MySQL container under ‘/var/lib/mysql’.

The Volumes section at the bottom specifies all the properties that were described above. Note that the compose file below has been tested using Portainer with Docker Compose version 2 and you can change this if needed.

version: '2'

# The volume that you want to define for use int he containers.    
    driver: local # Must be set to avoid issues.
      type: "nfs"
      o: "addr=my.nfs.server,rsize=65536,wsize=65536,timeo=14,tcp,rw,noatime"
      device: ":/volume1/mysql/"

    container_name: mysql
      MYSQL_ROOT_PASSWORD: somePassword
      - 3306:3306
      # The volume you have created in the 'volumes' section further below.
      - nfs-mysql-vol:/var/lib/mysql 
    image: 'mysql:latest'
    command: --default-authentication-plugin=mysql_native_password
    restart: always

NFS Volume Options

Additionally, you have various options available to help you configure the NFS volume for your container.

For example: “addr=my.nfs.server,rsize=65536,wsize=65536,timeo=14,tcp,rw,noatime”:

  • You can set the read and write size of your NFS to help increase the performance.
  • Also, you can also set the protocol to TCP, which allows only lost frames to be resent.

NFS Permissions

You cannot use a UID and GID parameter to when mounting NFS volumes via Docker. The UID and GID parameter is used by Autofs when setting up a CIFS connection. Anto made this mistake on a previous version of this post.

NFS permissions functions differently depending on whether you are trying to access your NFS as root or as a non-root user.

If you are root, then you are probably not exporting with the no_root_squash/no_mapping option. The root user can write files and use your preferred user id. You will get an “Operation not permitted” if you do not use no_mapping when trying to write a file with a different user id.

Docker runs all of its containers as the root user because it requires access to things like network configuration, processes, and the filesystem. The processes running inside your containers also run as root, which means they can write files on the NFS server.

On the container:

root@72ce0dc0b8f3:/var/www/html# id
uid=0(root) gid=0(root) groups=0(root)

On the NFS server:


If you are not root, then the user id may not be in sync between the client and the server. You will need to make sure the client and server match. Also, make sure you are not exporting with the all_squash option. You may have a more general permission issue if the user ids are the same.

As a side note –

The Synology NAS can make this step very hard, due to built-in user provisioning limitations.

About the Authors

Each member of Anto's editorial team is a Cloud expert in their own right. Anto Online takes great pride in helping fellow Cloud enthusiasts. Let us know if you have an excellent idea for the next topic!

Support the Cause

Support Anto Online and buy us a coffee. Anything is possible with coffee and code.

Buy me a coffee

2 Comments on “How to Mount an NFS Share Into a Container”

  1. Hi, thanks for the post. I am getting permission issues when I follow your instructions. Could you let me know where you set ‘uid=1024,gid=100’ as you mentioned?


Leave a Reply

Your email address will not be published. Required fields are marked *