Skip to main content

Docker Storage Prerequisites for GPU Splitting

Before you enable GPU splitting in the portal, you need to prepare Docker storage on the host. This page covers only the storage-side prerequisites and verification for lium gpu-splitting. After the host is ready, finish the portal setup from the Managing Nodes guide.

Before You Run the CLI​

The --device argument is only the storage target that LIUM will use for Docker storage during GPU splitting setup.

You do not need to:

  • pre-format it as XFS
  • mount it at /var/lib/docker
  • manually configure overlay2

LIUM handles partition creation, XFS formatting, mount setup, and Docker storage migration after the target passes safety checks.

Safe Device States​

LIUM will use the device when it is one of these states:

  • a blank whole disk
  • a whole disk with one unambiguous free-space region
  • an unused partition with no filesystem
  • an empty XFS partition with ftype=1

Device States That Will Be Rejected​

LIUM will skip or reject the device when it is:

  • the root disk
  • the current Docker backing device
  • mounted or otherwise in use
  • a partition with an existing non-XFS filesystem
  • a non-empty XFS partition
  • a disk with an ambiguous layout
  • a loop or device-mapper target

Prepare the Device​

The safest path is to attach a fresh extra SSD/NVMe and leave it unused and unmounted before you run the CLI.

  1. Attach a new extra disk.
  2. Make sure it is not your root disk.
  3. Make sure it is not the device currently backing /var/lib/docker.
  4. Pass that whole-disk path to the CLI.

Quick Checks​

Use these commands before running setup:

# See the candidate device, filesystem, and mount state
lsblk -o NAME,PATH,TYPE,FSTYPE,SIZE,MOUNTPOINTS

# See which device backs /
findmnt /

# See which device currently backs Docker storage
findmnt /var/lib/docker

If you want to reuse an existing XFS partition, confirm it is XFS with ftype=1:

sudo xfs_info /dev/<partition>

Common Remediation​

  • If the device is mounted, unmount it first and confirm nothing important is using it.
  • If the device has old filesystems or old data, the safest option is to use a different empty disk.
  • If you want to reuse the same disk and it is safe to erase, reset it to a clean disk or unused partition before rerunning the CLI.

Example: reset a dedicated extra disk so LIUM can partition and format it itself:

# Warning: destructive. Replace /dev/nvme1n1 with the extra disk you want to erase.
sudo umount /dev/nvme1n1p1 2>/dev/null || true
sudo parted -s /dev/nvme1n1 mklabel gpt

After that, rerun:

lium gpu-splitting check --device /dev/nvme1n1

Run the Storage Setup​

Use the CLI in this order:

# Inspect the host and confirm the device is eligible
lium gpu-splitting check --device /dev/<device>

# Apply the storage migration
sudo lium gpu-splitting setup --device /dev/<device>

# Verify the final state
lium gpu-splitting verify

What each command does:

  • check inspects the host and prints the exact storage plan without changing anything
  • setup performs the Docker storage migration required before GPU splitting can be enabled
  • verify confirms the final Docker storage state required for GPU splitting

Verify the Host​

After setup, confirm these requirements are satisfied:

  • Docker storage driver is overlay2
  • Docker backing filesystem is xfs
  • Supports d_type is true
  • /var/lib/docker is mounted with pquota or prjquota

Quick verification:

docker info
findmnt /var/lib/docker
lium gpu-splitting verify

Next Step: Enable GPU Splitting in the Portal​

After the host passes verification, finish GPU splitting setup in the portal:

  1. Open the Managing Nodes guide.
  2. Follow the Setting Minimum GPU Count for Rental steps.
  3. Return to this page if you need to re-check the storage prerequisites.

This page intentionally stops at host preparation. The portal-side minimum GPU count is the setting that actually enables GPU splitting for renters.

Troubleshooting​

If the CLI does not use the device you passed, check these first:

  • it is not the root or current Docker device
  • it is not mounted
  • it does not contain an existing non-XFS filesystem
  • it is not a non-empty XFS partition
  • the disk layout is simple enough for LIUM to classify safely

If you are unsure, the most reliable fix is to use a fresh extra disk and rerun lium gpu-splitting check --device /dev/<device>.