324 lines
No EOL
8.7 KiB
Markdown
324 lines
No EOL
8.7 KiB
Markdown
# Particle-OS Path Management Implementation
|
|
|
|
## Overview
|
|
|
|
This document describes the implementation of a configuration-based path management system for Particle-OS, designed to eliminate hardcoded paths and provide flexible, maintainable system initialization.
|
|
|
|
## Problem Statement
|
|
|
|
The original Particle-OS implementation had several issues:
|
|
1. **Hardcoded paths** scattered throughout scriptlets
|
|
2. **Inconsistent path references** (ubuntu-ublue vs particle-os)
|
|
3. **Manual directory creation** required for system operation
|
|
4. **No centralized path configuration** for easy customization
|
|
5. **Missing initialization commands** for system setup
|
|
|
|
## Solution Implementation
|
|
|
|
### 1. Configuration-Based Path System
|
|
|
|
#### New Configuration File: `src/apt-layer/config/paths.json`
|
|
|
|
```json
|
|
{
|
|
"system_paths": {
|
|
"root_dir": "/var/lib/apt-layer",
|
|
"config_dir": "/usr/local/etc/apt-layer",
|
|
"log_dir": "/var/log/apt-layer",
|
|
"cache_dir": "/var/cache/apt-layer",
|
|
"temp_dir": "/tmp/apt-layer"
|
|
},
|
|
"live_overlay_paths": {
|
|
"overlay_dir": "/var/lib/apt-layer/live-overlay",
|
|
"upper_dir": "/var/lib/apt-layer/live-overlay/upper",
|
|
"work_dir": "/var/lib/apt-layer/live-overlay/work",
|
|
"mount_point": "/var/lib/apt-layer/live-overlay/mount",
|
|
"state_file": "/var/lib/apt-layer/live-overlay.state",
|
|
"package_log": "/var/log/apt-layer/live-overlay-packages.log"
|
|
},
|
|
"deployment_paths": {
|
|
"deployments_dir": "/var/lib/apt-layer/deployments",
|
|
"backups_dir": "/var/lib/apt-layer/backups",
|
|
"images_dir": "/var/lib/apt-layer/images",
|
|
"layers_dir": "/var/lib/apt-layer/layers"
|
|
},
|
|
"bootloader_paths": {
|
|
"config_dir": "/etc/apt-layer/bootloader",
|
|
"kargs_dir": "/etc/apt-layer/kargs",
|
|
"efi_dir": "/boot/efi",
|
|
"boot_dir": "/boot"
|
|
},
|
|
"oci_paths": {
|
|
"containers_dir": "/var/lib/apt-layer/containers",
|
|
"images_dir": "/var/lib/apt-layer/oci-images",
|
|
"exports_dir": "/var/lib/apt-layer/exports"
|
|
},
|
|
"composefs_paths": {
|
|
"images_dir": "/var/lib/apt-layer/composefs",
|
|
"cache_dir": "/var/cache/apt-layer/composefs"
|
|
},
|
|
"fallback_paths": {
|
|
"legacy_root": "/var/lib/ubuntu-ublue",
|
|
"legacy_config": "/usr/local/etc/ubuntu-ublue",
|
|
"legacy_log": "/var/log/ubuntu-ublue"
|
|
},
|
|
"permissions": {
|
|
"root_dir_perms": "755",
|
|
"config_dir_perms": "755",
|
|
"log_dir_perms": "755",
|
|
"cache_dir_perms": "755",
|
|
"overlay_upper_perms": "700",
|
|
"overlay_work_perms": "700"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 2. New System Initialization Scriptlet
|
|
|
|
#### File: `src/apt-layer/scriptlets/08-system-init.sh`
|
|
|
|
This scriptlet provides comprehensive system initialization functionality:
|
|
|
|
- **`load_system_paths()`** - Loads paths from JSON configuration with fallbacks
|
|
- **`init_particle_system()`** - Creates all necessary directories and sets permissions
|
|
- **`reinit_particle_system()`** - Force recreation of system directories
|
|
- **`rm_init_particle_system()`** - Complete system cleanup and removal
|
|
- **`validate_system_paths()`** - Validates all required directories exist
|
|
- **`show_system_status()`** - Displays comprehensive system status
|
|
|
|
### 3. New Command-Line Interface
|
|
|
|
#### New Commands Added:
|
|
|
|
```bash
|
|
# Initialize Particle-OS system
|
|
sudo apt-layer --init
|
|
|
|
# Reinitialize Particle-OS system (force recreation)
|
|
sudo apt-layer --reinit
|
|
|
|
# Remove Particle-OS system (cleanup)
|
|
sudo apt-layer --rm-init
|
|
|
|
# Show Particle-OS system status
|
|
apt-layer --status
|
|
```
|
|
|
|
### 4. Updated Live Overlay System
|
|
|
|
The live overlay system now uses configuration-based paths:
|
|
|
|
- **Automatic directory creation** during initialization
|
|
- **Path validation** before overlay operations
|
|
- **Consistent path references** throughout the system
|
|
- **Fallback mechanisms** for backward compatibility
|
|
|
|
## Implementation Details
|
|
|
|
### Path Loading Strategy
|
|
|
|
1. **Primary**: Load from `paths.json` using `jq` if available
|
|
2. **Fallback**: Use default paths if `jq` is not available
|
|
3. **Legacy**: Support for legacy ubuntu-ublue paths during transition
|
|
|
|
### Directory Structure Created
|
|
|
|
```
|
|
/var/lib/apt-layer/
|
|
├── live-overlay/
|
|
│ ├── upper/
|
|
│ ├── work/
|
|
│ └── mount/
|
|
├── deployments/
|
|
├── backups/
|
|
├── images/
|
|
├── layers/
|
|
├── containers/
|
|
├── oci-images/
|
|
├── exports/
|
|
└── composefs/
|
|
|
|
/var/log/apt-layer/
|
|
├── apt-layer.log
|
|
└── live-overlay-packages.log
|
|
|
|
/var/cache/apt-layer/
|
|
└── composefs/
|
|
|
|
/usr/local/etc/apt-layer/
|
|
└── paths.json
|
|
|
|
/etc/apt-layer/
|
|
├── bootloader/
|
|
└── kargs/
|
|
```
|
|
|
|
### Permission Management
|
|
|
|
- **Main directories**: 755 (readable by all, writable by owner)
|
|
- **Overlay directories**: 700 (private to owner)
|
|
- **Log files**: 644 (readable by all, writable by owner)
|
|
- **Configuration files**: 644 (readable by all, writable by owner)
|
|
|
|
## Usage Examples
|
|
|
|
### Basic System Setup
|
|
|
|
```bash
|
|
# Initialize the system
|
|
sudo apt-layer --init
|
|
|
|
# Check system status
|
|
apt-layer --status
|
|
|
|
# Start live overlay
|
|
sudo apt-layer --live-overlay start
|
|
```
|
|
|
|
### System Maintenance
|
|
|
|
```bash
|
|
# Reinitialize system (force recreation)
|
|
sudo apt-layer --reinit
|
|
|
|
# Complete system cleanup
|
|
sudo apt-layer --rm-init
|
|
```
|
|
|
|
### Path Customization
|
|
|
|
1. **Edit configuration**: Modify `src/apt-layer/config/paths.json`
|
|
2. **Recompile**: Run `./compile.sh` in `src/apt-layer/`
|
|
3. **Reinitialize**: Run `sudo apt-layer --reinit`
|
|
|
|
## Testing
|
|
|
|
### Test Script: `test-path-management.sh`
|
|
|
|
A comprehensive test script validates:
|
|
|
|
1. **Command availability** - New commands are properly integrated
|
|
2. **System initialization** - All directories are created correctly
|
|
3. **Path consistency** - Configuration-based paths work throughout
|
|
4. **Live overlay functionality** - Overlay system works with new paths
|
|
5. **System cleanup** - Removal commands work correctly
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
# Make test script executable
|
|
chmod +x test-path-management.sh
|
|
|
|
# Run comprehensive tests
|
|
./test-path-management.sh
|
|
```
|
|
|
|
## Benefits
|
|
|
|
### 1. Maintainability
|
|
- **Centralized configuration** - All paths in one JSON file
|
|
- **Easy customization** - Modify paths without code changes
|
|
- **Version control friendly** - Configuration changes are trackable
|
|
|
|
### 2. Reliability
|
|
- **Automatic initialization** - No manual directory creation required
|
|
- **Path validation** - System checks for required directories
|
|
- **Fallback mechanisms** - Graceful degradation if configuration is missing
|
|
|
|
### 3. Flexibility
|
|
- **Customizable paths** - Easy to change system layout
|
|
- **Environment-specific configs** - Different paths for different environments
|
|
- **Legacy support** - Backward compatibility during transition
|
|
|
|
### 4. User Experience
|
|
- **Simple commands** - Clear, intuitive initialization commands
|
|
- **Status reporting** - Comprehensive system status information
|
|
- **Error handling** - Clear error messages and recovery options
|
|
|
|
## Migration Guide
|
|
|
|
### For Existing Installations
|
|
|
|
1. **Backup existing data**:
|
|
```bash
|
|
sudo cp -r /var/lib/ubuntu-ublue /var/lib/ubuntu-ublue.backup
|
|
```
|
|
|
|
2. **Update to new version**:
|
|
```bash
|
|
git pull
|
|
cd src/apt-layer
|
|
./compile.sh
|
|
```
|
|
|
|
3. **Initialize new system**:
|
|
```bash
|
|
sudo apt-layer --init
|
|
```
|
|
|
|
4. **Migrate data** (if needed):
|
|
```bash
|
|
sudo cp -r /var/lib/ubuntu-ublue.backup/* /var/lib/apt-layer/
|
|
```
|
|
|
|
5. **Verify functionality**:
|
|
```bash
|
|
apt-layer --status
|
|
```
|
|
|
|
### For New Installations
|
|
|
|
1. **Clone repository**:
|
|
```bash
|
|
git clone <repository-url>
|
|
cd particle-os-tools
|
|
```
|
|
|
|
2. **Compile system**:
|
|
```bash
|
|
cd src/apt-layer
|
|
./compile.sh
|
|
```
|
|
|
|
3. **Initialize system**:
|
|
```bash
|
|
sudo apt-layer --init
|
|
```
|
|
|
|
4. **Verify installation**:
|
|
```bash
|
|
apt-layer --status
|
|
```
|
|
|
|
## Future Enhancements
|
|
|
|
### Planned Improvements
|
|
|
|
1. **Environment-specific configurations** - Different paths for development/production
|
|
2. **Dynamic path resolution** - Runtime path determination based on environment
|
|
3. **Configuration validation** - JSON schema validation for path configurations
|
|
4. **Migration tools** - Automated migration from legacy installations
|
|
5. **Backup/restore** - System state backup and restoration capabilities
|
|
|
|
### Configuration Extensions
|
|
|
|
```json
|
|
{
|
|
"environment": "production",
|
|
"custom_paths": {
|
|
"data_dir": "/opt/particle-os/data",
|
|
"backup_dir": "/mnt/backup/particle-os"
|
|
},
|
|
"validation": {
|
|
"check_permissions": true,
|
|
"check_disk_space": true,
|
|
"min_disk_space_gb": 10
|
|
}
|
|
}
|
|
```
|
|
|
|
## Conclusion
|
|
|
|
The new path management system provides a robust, maintainable foundation for Particle-OS development. By centralizing path configuration and providing comprehensive initialization tools, the system is now more flexible, reliable, and user-friendly.
|
|
|
|
The implementation maintains backward compatibility while providing a clear migration path to the new configuration-based approach. The comprehensive testing ensures system reliability and the modular design allows for future enhancements. |