particle-os-tools/docs/composefs/README.md

ComposeFS Documentation

Overview

ComposeFS is the immutable filesystem backend for Ubuntu uBlue systems. It provides the foundation for atomic, layered system updates similar to OSTree but using squashfs and overlayfs technologies.

ComposeFS Alternative Script

The composefs-alternative.sh script provides:

• Image Creation: Create ComposeFS images from directories
• Image Mounting: Mount ComposeFS images for access
• Image Management: List, remove, and manage ComposeFS images
• Status Information: Get system status and image information
• Integration API: Clean interface for other scripts

Key Features

• Immutable Images: Squashfs-based immutable filesystem images
• Layer Support: Multiple layers can be combined using overlayfs
• Atomic Operations: All operations are atomic and recoverable
• Efficient Storage: Deduplication and compression for space efficiency
• Boot Integration: Seamless integration with bootloader systems

Documentation Files

Core Documentation

• composefs-guide.md - Comprehensive user guide
• composefs-api.md - API reference and command documentation
• composefs-architecture.md - Technical architecture details

Technical Documentation

• composefs-performance.md - Performance considerations and optimization
• composefs-troubleshooting.md - Common issues and solutions
• composefs-migration.md - Migration from other filesystem technologies

Quick Start

# Create a ComposeFS image
composefs-alternative.sh create my-image /path/to/source

# Mount a ComposeFS image
composefs-alternative.sh mount my-image /mnt/image

# List all images
composefs-alternative.sh list-images

# Get image information
composefs-alternative.sh info my-image

# Remove an image
composefs-alternative.sh remove my-image

Integration

ComposeFS integrates with:

• apt-layer.sh: For layer creation and management
• bootloader-integration.sh: For boot image registration
• oci-integration.sh: For OCI image conversion
• ublue-config.sh: For unified configuration

Architecture

ComposeFS provides:

• Squashfs Images: Compressed, immutable filesystem images
• Overlayfs Layers: Multiple layers combined for final filesystem
• Atomic Operations: All operations are atomic and recoverable
• Efficient Storage: Deduplication and compression
• Boot Compatibility: Compatible with standard bootloader systems

Performance Characteristics

• Read Performance: Excellent read performance due to compression
• Write Performance: Immutable by design, changes create new layers
• Storage Efficiency: High compression ratios and deduplication
• Boot Performance: Fast boot times with optimized images

Security Features

• Immutable Images: Cannot be modified once created
• Integrity Verification: Optional integrity checking
• Atomic Updates: All-or-nothing update semantics
• Rollback Support: Easy rollback to previous images

Development Status

ComposeFS is production-ready with:

• ✅ Immutable filesystem support
• ✅ Layer management
• ✅ Atomic operations
• ✅ Boot integration
• ✅ Performance optimization
• ✅ Security features

For more information, see the individual documentation files listed above.