docs: Add documentation for resolving XFS filesystem requirement on non-xfs root

[Dafeigy]

This PR adds documentation to help users who encounter the following error during the Cube Sandbox one-click installation:

ERROR: The filesystem that will host /data/cubelet is on '/' (type: ext4), which is not XFS.

related to #245 .

Problem

Many users (especially those on Ubuntu dual-boot systems) have their root filesystem formatted as ext4. The one-click installer requires /data/cubelet to reside on an XFS filesystem, but repartitioning a live system is risky and often not possible.

Solution

The added guide provides a non-destructive workaround using a loopback file:

1. Create a sparse file on the ext4 root (e.g., 20 GB).
2. Format it as XFS.
3. Mount it at /data/cubelet.
4. Persist the mount via /etc/fstab.

This approach works without altering existing partitions and is safe for dual-boot environments.

Testing

• Tested on Ubuntu 22.04 with an ext4 root and no free partitions.
• After following the steps, df -T /data/cubelet reports xfs, and the Cube Sandbox installer proceeds without errors.

Notes

• Adjust the file size according to your Sandbox storage needs.
• The loopback file is created as a sparse file to avoid pre-allocating all disk space.

Please review and merge if appropriate. Thank you!

[Dafeigy]

#253 also encounter this. I think it may be better written in the guide rather than the install.sh script.

[fslongjin]

/cubebot review

[github-actions]

Claude finished @fslongjin's task in 56s —— View job

---

Review Checklist

• Read changed files and PR context
• Analyzed documentation changes
• Checked install.sh for related error handling
• Review and suggestions compiled

---

Code Review: docs/guide/self-build-deploy.md and docs/zh/guide/self-build-deploy.md

This PR adds documentation for using a loopback file to satisfy the XFS requirement for /data/cubelet on systems with an ext4 root filesystem. Overall this is a helpful addition that addresses a real pain point (issue #245). The instructions are clear and the implementation is correct.

Positive Points

• Non-destructive approach — avoids repartitioning, which is especially valuable for dual-boot users
• Both languages updated — English and Chinese docs are consistent
• Includes verification step — df -T /data/cubelet gives users confidence the setup worked
• Sparse file — using count=0 seek=20 with dd avoids pre-allocating the full 20 GB

Suggestions

1. mkfs.xfs requires xfsprogs to be installed

The mkfs.xfs command is not available by default on Ubuntu. Consider adding a prerequisite step or a note:

# Ubuntu/Debian
sudo apt-get install xfsprogs -y

# CentOS/RHEL
sudo yum install xfsprogs -y

2. fallocate vs sparse files in the comment

The comment # Or use fallocate for speed: sudo fallocate -l 20G /xfs-loopfile could mislead. Unlike dd count=0 seek=N, fallocate on ext4 allocates blocks immediately (it does not create a sparse file). A user following the fallocate path would lose the space-saving benefit of the sparse approach. Consider either:

• Removing the fallocate alternative to avoid confusion, or
• Using truncate -s 20G /xfs-loopfile which truly creates a sparse file and is instant like fallocate, or
• Adding a note that fallocate pre-allocates the space

3. Duplicate /etc/fstab entries on re-run

The tee -a /etc/fstab approach appends unconditionally. If a user re-runs the steps (e.g., during reinstallation after reading the "Reinstall" section), they'll get a duplicate fstab entry. Consider suggesting the user check for an existing entry:

grep -q '/xfs-loopfile' /etc/fstab || echo '/xfs-loopfile /data/cubelet xfs loop 0 2' | sudo tee -a /etc/fstab

4. File location at /xfs-loopfile

Placing the loop file at /xfs-loopfile (root of /) is functional but non-standard. Consider suggesting /var/lib/cube-sandbox/xfs-loopfile as an alternative, or at least noting that the user should place it on a partition with sufficient free space.

5. Minor: align English and Chinese note wording

The English note says:

The loop file must be on a filesystem that supports sparse files (ext4 does)

The Chinese note says:

文件实际放在 / (ext4) 上，但挂载到 /data/cubelet 后，Cube 看到的就是 XFS 了

These convey slightly different information. Consider aligning them — the English version explains why this works (sparse file support), while the Chinese version focuses on the effect (Cube sees XFS). Both are useful; consider incorporating both perspectives into each version.

Summary

The PR is ready to merge — the suggestions above are minor improvements, not blockers. The documentation is correct, addresses a common user issue, and follows the existing doc style.

[fslongjin]

Hi @Dafeigy,

Thanks for the PR! The DCO (Developer Certificate of Origin) check is failing. You need to add a Signed-off-by line to your commit message.

You can fix this by amending your commit:

git commit --amend --signoff
git push --force

This will append a Signed-off-by: Your Name <your-email@example.com> line to the commit message, which is required by the project's DCO policy. See DCO for details.

[Dafeigy]

Hi @Dafeigy,

Thanks for the PR! The DCO (Developer Certificate of Origin) check is failing. You need to add a Signed-off-by line to your commit message.

You can fix this by amending your commit:

git commit --amend --signoff
git push --force

This will append a Signed-off-by: Your Name <your-email@example.com> line to the commit message, which is required by the project's DCO policy. See DCO for details.

Done. Thanks for reply~

[kinwin-ustc]

Hi @Dafeigy Can you fix the issues mentioned in the cubebot review?

[Dafeigy]

Hi @kinwin-ustc Yes, I make some changes to the instructions following the suggestions given by Cubebot.