fixed paths, created ci/cd workflow
Some checks failed
Compile apt-layer / compile (push) Failing after 2s
Some checks failed
Compile apt-layer / compile (push) Failing after 2s
This commit is contained in:
parent
14d7da71e8
commit
29b9675689
26 changed files with 7407 additions and 358 deletions
324
PATH_MANAGEMENT_IMPLEMENTATION.md
Normal file
324
PATH_MANAGEMENT_IMPLEMENTATION.md
Normal file
|
|
@ -0,0 +1,324 @@
|
|||
# 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue