Skip to main content

Persistant folders: Using and configuring bind mounts

Overview​

Bind mounts are a powerful feature in Docker that allow you to map directories from your host machine to your containers. This ensures that data persists even when containers are restarted and enables seamless interaction between the host system and the containerized application.

In this tutorial, we will explain what bind mounts are, how to configure them in a docker-compose.yaml file, and walk through a practical example.

Videotutorial​

See also...

Watch this tutorial on Persistent Folders - Bind Mounts.

What Are Bind Mounts?​

A bind mount is a mechanism that links a directory or file on the host machine to a directory or file inside the container. Unlike Docker volumes, which are managed by Docker itself, bind mounts provide direct access to the specified directory on the host system.

Key Benefits of Bind Mounts:​

  • Persistent storage: Data remains available even if the container is removed.
  • Easy file sharing: Allows for direct modification of files between the host and container.
  • Development convenience: Developers can work on files locally without rebuilding the container.

Configuring Bind Mounts in docker-compose.yaml​

To define a bind mount in a docker-compose.yaml file, you need to specify the volumes directive within a service. The format follows:

services:
  app:
    image: filebrowser/filebrowser:latest
    volumes:
      - /path/on/host:/path/in/container
warning

In Barbara, bind mounts are subject to specific limitations to ensure data security and isolation. These restrictions include:

  • Root Folder Restriction: Bind mounts are not permitted within the root directory (/), with the sole exception of /sys.
  • ".." Path Restriction: Paths for bind mounts cannot include the .. sequence (parent directory reference).
  • Allowed Prefixes: Bind mount paths are restricted to the following prefixes:
    • ./persist: Designated for persistent data storage using bind mounts.
    • ./appconfig: Contains application configuration and global configuration files on edge nodes.
    • /sys: Provides user-space programs with access to kernel and hardware information.

Example Configuration​

The following docker-compose.yaml file demonstrates how to use a bind mount to share a local directory with the Filebrowser container:

version: '3.8'
services:
  filebrowser:
    image: filebrowser/filebrowser:latest
    ports:
      - "8080:80"
    volumes:
      - ./persist/data:/srv

In this setup:

  • The ./persist/data directory on the host is mapped to /srv inside the container.
  • Any files placed in ./persist/data on the host will be accessible through the Filebrowser web interface.
Did you know?

Application cards feature a dedicated Persistent Folder section that allows users to check the size of the bind-mounted folder and delete it remotely.

Hands-on Practice 1: Using Bind Mounts with Filebrowser Locally​

Let's walk through a practical example to see bind mounts in action.

Step 1: Create a Local Directory​

Run the following command to create a directory and add some sample files:

mkdir persist
mkdir persist/data
echo "Sample file" > persist/data/sample.txt

Step 2: Create the docker-compose.yaml File​

Create a file named docker-compose.yaml with the following content:

version: '3.8'
services:
  filebrowser:
    image: filebrowser/filebrowser:latest
    ports:
      - "8080:80"
    volumes:
      - ./persist/data:/srv

Step 3: Start the Container​

Run the following command to start the service:

docker-compose up -d

Step 4: Access the Filebrowser Interface​

Open a browser and go to http://localhost:8080. You should see the Filebrowser interface displaying the contents of the data directory.

Data folder contents

Data folder contents

Step 5: Modify the Host Directory​

Add a new file to the persist/data directory on the host system:

echo "New file in bind mount" > persist/data/newfile.txt

Refresh the Filebrowser web interface, and the new file should appear instantly without restarting the container.

Data folder contents

Data folder contents

Did you know...

Docker bind mounts create a live, bidirectional link between a host folder and a container folder, meaning changes in either location are instantly reflected in the other. This real-time synchronization enables efficient data sharing and persistence, as the data resides on the host and survives container changes.

Step 6: Stop and Remove the Container​

When done, clean up the environment by running:

docker-compose down

Hands-on Practice 2: Deploying Filebrowser to a Barbara Edge Node​

Now, let's deploy the Filebrowser application to a Barbara Edge Node and manage its persistent folder from the Barbara Panel.

Step 1: ZIP the docker-compose.yaml File​

Compress the docker-compose.yaml file:

zip -r filebrowser_app.zip docker-compose.yaml
note

This approach avoids uploading the folder contents directly; only the docker-compose.yaml file is transferred. If you need to include the contents of the persist/data folder, you'll need to create a Dockerfile. This Dockerfile should start with the filebrowser image and then copy the persist/data folder into the image.

Step 2: Upload the Application to Barbara’s Library​

  1. Go to your Barbara Panel's Library.
  2. Click on "Add New Application" and name it filebrowser. In case the application exists just go to the next step.
  3. Once created, add a new version and upload the filebrowser_app.zip file.

Step 3: Deploy the Application to an Edge Node​

  1. Select an edge node from your Barbara Panel.
  2. Click "Add Card" and choose "Add a New Application".
  3. Select the filebrowser application and deploy it to the node.

Step 4: Access the Filebrowser Interface​

  1. Open a browser and navigate to http://[IP_OF_YOUR_NODE]:8080.
  2. You should see the Filebrowser interface, now running on your remote edge node.
  3. Upload some contents to the filebrowser application.

Data folder contents

Data folder contents

Step 5: Manage the Persistent Folder from Barbara Panel​

  1. Navigate to the "Node Details" section in your Barbara Panel.
  2. Select the "Apps & Models" tab to view the Docker application card.
  3. Within this card, locate the "Persistent Folder" section. Here you will find:
  • The current size of the persistent folder.
  • A button to delete the data within the folder, effectively emptying it.

Persistant folder section

Persistant folder section

  1. Press the "Delete" button in the "Persistent Folder" segment.
  2. Check that now, the filebrowser data is empty.

Step 6: Updating the application version without losing the data stored in the persistent folder​

danger

Uninstalling an application will also delete its persistent folder. Therefore, if you're installing a new version of the same application, be aware that uninstalling the old version first will result in data loss.

To avoid this, and preserve your persistent data, it's strongly recommended to use the "Update Version" option. This will replace the existing application version with the new one while retaining the data stored in the persistent folder.

Update version

Update version

Summary​

Bind mounts offer a straightforward yet powerful mechanism for managing persistent data and streamlining development within Docker environments. By utilizing bind mounts in your docker-compose.yaml file, you can enable seamless interaction between your host system and containers, improving development and deployment efficiency.

Furthermore, integrating bind mounts with the Barbara platform enhances control and accessibility of persistent storage on edge nodes.

However, bind mounts have a key limitation: uninstalling the application will result in the loss of any stored data. Therefore, the next chapter of this tutorial will introduce Docker volumes, which provide a solution to this issue.