Do I have docker storage settings configured correctly?

Note: I am using BTRFS for my cache drive.

Docker data-root: Directory vs. Image File?

Is there a performance trade off between using a directory vs. image file?

I prefer docker "data-root" to be a directory rather than a virtual disk (file), so I don't have to keep expanding the virtual drive.

Any other tradeoffs to consider?

Docker storage driver: Native vs. Overlay2?

What should the storage driver be: Native or Overlay2?

I am currently using "Native", and I see a folder called "btrfs" with another folder "subvolumes", and with a lot of files.

Don't know why. Maybe I should use "overlay2"?

What are the tradeoffs? Is there a performance tradeoff? Integrity?

Thank you.

Unraid's Docker storage system utilizes a virtual disk image file named docker.img to store container data and programs. This file, by default, resides in the system user share, often leveraging the cache pool for enhanced performance. The docker.img file employs the BTRFS file system and is mounted internally by Unraid. (due to USB mutable ram OS, think of the docker img of a VMs hard drive that we run on the host)

Key aspects of Unraid's Docker storage system:

• docker.img:

  This central file contains all the data and programs for each Docker container running on Unraid, excluding application data (appdata) and other items explicitly mapped to the main array.

• Cache Pool Integration:

  Storing docker.img on the cache pool, typically composed of SSDs, is recommended for optimal performance due to faster read/write speeds.

• Appdata Management:

  Application-specific data, such as settings and libraries, is typically stored outside the container, often in a dedicated appdata user share. This approach ensures data persistence across container updates or reinstalls. a default path for unraid templates containt dockers configuration data.

• Volume Mappings:

  When configuring Docker containers, volumes are mapped from within the container to specific shares on the Unraid server. This allows containers to access data stored on the main array or cache pool, while perceiving it as local to the container. other paths you want a docker to be able to read and inteact onthe unraid host.

• Configuration Storage:

  Unraid saves Docker container configurations as VM XML templates on the flash drive, facilitating easy reinstallation or restoration of containers with preferred settings.

most of theses questions on this can be found in the docs and release notes:
https://docs.unraid.net/unraid-os/using-unraid-to/run-docker-containers/overview/
https://docs.unraid.net/unraid-os/using-unraid-to/run-docker-containers/managing-and-customizing-containers/

Regardein the root file locaiton. Here is some old data regarding the docker .img file type to use for FS data
https://forums.unraid.net/topic/126557-6103-docker-data-root-options/

Please also Review: https://www.reddit.com/r/unRAID/comments/t2ll3w/dockers_folder_or_image/

So....

Docker “Image File” vs Docker “Directory” for Data-Root (vDisk vs folder)

What they are:

• Image File (vdisk / docker.img / vDisk): Docker data + appdata are stored inside a large file, formatted with a filesystem inside (e.g. BTRFS or XFS), that acts like a block device. That file is mounted and Docker uses it as its data-root (where containers, images, volumes metadata live).

• Directory / “folder” mode: Docker data-root is a folder on a normal filesystem (e.g. your cache drive or share). Containers and images live as files/subfolders rather than inside a block image.

Docker Storage Driver: “Native” vs “Overlay2”

This one is a little more subtle.

• Unraid in some contexts uses a “native” storage driver. That generally means using the backend’s filesystem’s driver / default behavior. Depending on what the underlying FS is (BTRFS, ZFS, XFS, etc.), “native” can map to different things.

• OverlayFS / overlay2 is a union filesystem technique that Docker uses commonly on Linux: image layers + container layers get stacked, with upper/lower/merged dirs. It has been the recommended storage driver for many Linux distributions.

The storage driver docker docs data info:
https://docs.docker.com/engine/storage/drivers/select-storage-driver/

Recommend setup use case Form personal experience with unraids docker systems...

I recommend using the vdisk xfs docker img file and native storage driver for dockers on unriad.

This has been my default configurations following the docker release and unraid OS updates over the years.

To use appdata on xfs/btrfs/zfs in the array and/or a cache pools of disk... As some of these settings are needed and dictated more from the hardware your running, the storage options you have and what files system format you are using and wanting to interact with.

So, regarding the performance questions...

Docker Data-Root: Directory vs Image File

• Image file (docker.img / vdisk)

  • Pros: One big file is simple for mover/backups. Less metadata overhead when copying/moving.

  • Cons: Fixed size → if it fills up, you must expand manually. Adds an extra filesystem layer (Unraid mounts a loop device on top of your cache FS). That indirection can add slight overhead in metadata operations, especially on BTRFS. (I recomend 100 GB docker size for docker logs, docker image and adation data taht builds and gorws inside of containers.)

    • 

  • Performance impact: On SSD/NVMe cache the penalty is small, but still an extra layer of abstraction.

• Directory (folder mode on BTRFS cache)

  • Pros: Direct I/O to the underlying FS, no need for resizing, fewer layers. On fast BTRFS SSDs this is often faster for high-IOPS workloads (lots of small files).

  • Cons: If mover ever has to relocate appdata, it must copy many small files (slower maintenance). Backups/restores less convenient than one file.

    • Watch share setting... appdata should be a single primary location!

    • 

    • 

  • Performance impact: Generally equal or better than an image file if you’re already on a dedicated SSD/NVMe cache.

Conclusion: For performance, directory mode is typically the better choice on a BTRFS cache. The only downside is convenience (harder to move/backup vs one vdisk).

Docker Storage Driver: Native vs Overlay2

• overlay2

  • The Linux kernel’s optimized union filesystem. Handles image layering efficiently.

  • Generally best performance for container start/stop, builds, and layer management.

  • Lower copy-up overhead, faster metadata handling in most modern kernels.

  • Recommended by Docker upstream as the default driver for almost all distros.

• native (btrfs driver)

  • Stores container layers as BTRFS subvolumes (which is why you see btrfs/subvolumes).

  • Gives you CoW and snapshot features at the filesystem level.

  • Can become slower under heavy workloads with lots of layers or many small file changes (metadata overhead in BTRFS).

  • More complex fragmentation behavior, sometimes needs balance/defrag maintenance.

Conclusion:

• overlay2 on top of BTRFS cache → usually better raw performance and less maintenance hassle.

• native (btrfs driver) → offers advanced snapshooting features but can be slower and heavier in metadata overhead.

Recommendation for your setup (BTRFS cache, SSD/NVMe):

• Data-root as a directory → to avoid vdisk overhead and resizing.

• overlay2 as the storage driver → for faster, leaner container operations.

*Giving the performance over unraids default configuration and ease of backup.