robojerk/particle-os-tools

Fork 0

robojerk 29b9675689

Compile apt-layer / compile (push) Failing after 2s

Details

fixed paths, created ci/cd workflow

2025-07-14 14:22:06 -07:00

8.7 KiB

Raw Blame History

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:

Hardcoded paths scattered throughout scriptlets
Inconsistent path references (ubuntu-ublue vs particle-os)
Manual directory creation required for system operation
No centralized path configuration for easy customization
Missing initialization commands for system setup

Solution Implementation

1. Configuration-Based Path System

New Configuration File: `src/apt-layer/config/paths.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:

# 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

Primary: Load from paths.json using jq if available
Fallback: Use default paths if jq is not available
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

# Initialize the system
sudo apt-layer --init

# Check system status
apt-layer --status

# Start live overlay
sudo apt-layer --live-overlay start

System Maintenance

# Reinitialize system (force recreation)
sudo apt-layer --reinit

# Complete system cleanup
sudo apt-layer --rm-init

Path Customization

Edit configuration: Modify src/apt-layer/config/paths.json
Recompile: Run ./compile.sh in src/apt-layer/
Reinitialize: Run sudo apt-layer --reinit

Testing

Test Script: `test-path-management.sh`

A comprehensive test script validates:

Command availability - New commands are properly integrated
System initialization - All directories are created correctly
Path consistency - Configuration-based paths work throughout
Live overlay functionality - Overlay system works with new paths
System cleanup - Removal commands work correctly

Running Tests

# 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

Backup existing data:

sudo cp -r /var/lib/ubuntu-ublue /var/lib/ubuntu-ublue.backup

Update to new version:
```
git pull
cd src/apt-layer
./compile.sh
```
Initialize new system:
```
sudo apt-layer --init
```

Migrate data (if needed):

sudo cp -r /var/lib/ubuntu-ublue.backup/* /var/lib/apt-layer/

Verify functionality:
```
apt-layer --status
```

For New Installations

Clone repository:

git clone <repository-url>
cd particle-os-tools

Compile system:
```
cd src/apt-layer
./compile.sh
```
Initialize system:
```
sudo apt-layer --init
```
Verify installation:
```
apt-layer --status
```

Future Enhancements

Planned Improvements

Environment-specific configurations - Different paths for development/production
Dynamic path resolution - Runtime path determination based on environment
Configuration validation - JSON schema validation for path configurations
Migration tools - Automated migration from legacy installations
Backup/restore - System state backup and restoration capabilities

Configuration Extensions

{
  "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.

8.7 KiB Raw Blame History