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.

[kinwin-ustc]

/cubebot review

[github-actions]

Claude finished @kinwin-ustc's task in 45s —— View job

---

Review Checklist

• Read changed files and PR context
• Analyzed all diffs between English and Chinese docs
• Checked if previous review suggestions were addressed
• Compiled final review findings

---

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

Previous Suggestions — Addressed ✅

The author has addressed all suggestions from the previous review:

Suggestion	Status
Add xfsprogs install step	✅ Done (lines 134-137 in English, 130-135 in Chinese)
Remove fallocate alternative	✅ Done — sparse-only approach used
Guard against duplicate /etc/fstab entries	✅ Done — grep -q ... || echo ... pattern
Move loop file from / to a standard path	✅ Done — now at /var/lib/cube-sandbox/xfs-loopfile
Align EN and ZH note wording	✅ Better aligned — both mention sparse file support

---

Remaining Issues

1. RHEL/CentOS install command is broken — both English (line 137) and Chinese (line 134)

# sudo yum update && install xfsprogs -y

The install command is missing yum (and sudo for the second command). This would fail if uncommented. Should be:

# sudo yum update && sudo yum install xfsprogs -y

Fix this →

2. Chinese doc is missing the "FileSystem: XFS" prerequisite — docs/zh/guide/self-build-deploy.md

The English doc correctly adds | FileSystem | XFS | to the prerequisites table (line 30), but the Chinese doc does not have a corresponding entry. This should be added for consistency.

3. Minor typo in Chinese note — docs/zh/guide/self-build-deploy.md line 151

seed should be seek:

你可以自行通过 `seek` 和 `count` 的调整以适配当前的硬件条件。

---

Additional Observations

• Verification step is clear: df -T /data/cubelet with expected output is present in both docs.
• Sparse file approach is correct: bs=1G count=0 seek=20 creates a truly sparse file without pre-allocating blocks.
• DCO is now passing: The DCO check issue from the previous review has been resolved.

Summary

The PR is in good shape and addresses a real user pain point (issue #245). The three issues above are small fixes — once addressed, this is ready to merge.

---