Initial commit: Particle-OS tools repository

- Complete Particle-OS rebranding from uBlue-OS - Professional installation system with standardized paths - Self-initialization system with --init and --reset commands - Enhanced error messages and dependency checking - Comprehensive testing infrastructure - All source scriptlets updated with runtime improvements - Clean codebase with redundant files moved to archive - Complete documentation suite
2025-07-11 21:14:33 -07:00 · 2025-07-11 21:14:33 -07:00 · 74c7bede5f
commit 74c7bede5f
125 changed files with 66318 additions and 0 deletions
--- a/INSTALLATION.md
+++ b/INSTALLATION.md
@ -0,0 +1,194 @@
+# Particle-OS Installation Guide
+
+This guide explains how to install Particle-OS tools on your system using the standardized installation process.
+
+## Quick Installation
+
+For a complete installation with backup and verification:
+
+```bash
+# Clone the repository
+git clone <repository-url>
+cd Particle-OS/tools
+
+# Run the installation script
+sudo ./install-particle-os.sh
+```
+
+## Development Installation
+
+For quick reinstallation during development (no backups):
+
+```bash
+# Quick development install
+sudo ./dev-install.sh
+```
+
+## What Gets Installed
+
+The installation script installs the following tools to `/usr/local/bin/`:
+
+| Source Script | Installed As | Purpose |
+|---------------|--------------|---------|
+| `apt-layer.sh` | `apt-layer` | Package layer management |
+| `composefs-alternative.sh` | `composefs` | ComposeFS image management |
+| `bootc-alternative.sh` | `bootc` | Bootable container management |
+| `bootupd-alternative.sh` | `bootupd` | Bootloader management |
+| `orchestrator.sh` | `particle-orchestrator` | System orchestration |
+| `oci-integration.sh` | `particle-oci` | OCI integration |
+| `particle-logrotate.sh` | `particle-logrotate` | Log rotation management |
+
+**Note**: The `fsverity` command is provided by the Ubuntu `fsverity` package and should be installed separately:
+```bash
+sudo apt install -y fsverity
+```
+
+## Configuration
+
+The installation script also installs:
+- `particle-config.sh` → `/usr/local/etc/particle-config.sh`
+
+## Post-Installation Setup
+
+After installation, initialize the Particle-OS system:
+
+```bash
+# Install system dependencies (if not already installed)
+sudo apt install -y fsverity
+
+# Initialize the system
+sudo apt-layer --init
+
+# Verify installation
+particle-orchestrator help
+```
+
+## Verification
+
+Check that all tools are properly installed:
+
+```bash
+# Check if tools are in PATH
+which apt-layer
+which composefs
+which bootc
+which bootupd
+which particle-orchestrator
+
+# Test basic functionality
+apt-layer --help
+composefs --help
+particle-orchestrator help
+```
+
+## Uninstallation
+
+To completely remove Particle-OS tools:
+
+```bash
+# Remove all installed scripts
+sudo rm -f /usr/local/bin/apt-layer
+sudo rm -f /usr/local/bin/composefs
+sudo rm -f /usr/local/bin/bootc
+sudo rm -f /usr/local/bin/bootupd
+sudo rm -f /usr/local/bin/particle-orchestrator
+sudo rm -f /usr/local/bin/particle-oci
+sudo rm -f /usr/local/bin/particle-logrotate
+
+# Remove configuration
+sudo rm -f /usr/local/etc/particle-config.sh
+
+# Remove data directories (optional - will remove all Particle-OS data)
+sudo rm -rf /var/lib/particle-os
+sudo rm -rf /var/log/particle-os
+sudo rm -rf /var/cache/particle-os
+
+# Note: fsverity is a system package and should be removed separately if desired:
+# sudo apt remove fsverity
+
+## Backup and Recovery
+
+The installation script automatically creates backups of existing installations:
+
+- Backups are stored as `script.backup.YYYYMMDD_HHMMSS`
+- Example: `/usr/local/bin/apt-layer.backup.20250127_143022`
+
+To restore from backup:
+
+```bash
+# List available backups
+ls -la /usr/local/bin/*.backup.*
+
+# Restore a specific backup
+sudo cp /usr/local/bin/apt-layer.backup.20250127_143022 /usr/local/bin/apt-layer
+sudo chmod +x /usr/local/bin/apt-layer
+```
+
+## Troubleshooting
+
+### Permission Denied
+```bash
+# Ensure script is executable
+chmod +x install-particle-os.sh
+
+# Run with sudo
+sudo ./install-particle-os.sh
+```
+
+### Script Not Found
+```bash
+# Check if script exists in current directory
+ls -la *.sh
+
+# Ensure you're in the correct directory
+pwd
+```
+
+### PATH Issues
+```bash
+# Check if /usr/local/bin is in PATH
+echo $PATH | grep /usr/local/bin
+
+# Add to PATH if needed (add to ~/.bashrc or ~/.profile)
+export PATH="/usr/local/bin:$PATH"
+```
+
+### Configuration Issues
+```bash
+# Check if configuration is installed
+ls -la /usr/local/etc/particle-config.sh
+
+# Reinstall configuration
+sudo cp particle-config.sh /usr/local/etc/
+```
+
+## Development Workflow
+
+For developers working on Particle-OS:
+
+1. **Make changes** to scripts in the project directory
+2. **Quick reinstall** with `sudo ./dev-install.sh`
+3. **Test changes** with the installed tools
+4. **Repeat** as needed
+
+The development install script skips backups and verification for faster iteration.
+
+## System Requirements
+
+- Linux system (Ubuntu/Debian recommended)
+- Root access (sudo)
+- Bash shell
+- Basic system utilities (cp, chmod, chown, etc.)
+- fsverity package (for file integrity verification)
+  ```bash
+  sudo apt install -y fsverity
+  ```
+
+## Next Steps
+
+After installation:
+
+1. Read the [User Guide](docs/README.md) for usage examples
+2. Check the [TODO List](TODO.md) for current development status
+3. Review the [Changelog](src/apt-layer/CHANGELOG.md) for recent updates
+4. Join the community for support and contributions