particle-os-tools/INSTALLATION.md

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:

# 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):

# 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/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:

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:

# 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:

# 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:

# 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

# Ensure script is executable
chmod +x install-particle-os.sh

# Run with sudo
sudo ./install-particle-os.sh

Script Not Found

# Check if script exists in current directory
ls -la *.sh

# Ensure you're in the correct directory
pwd

PATH Issues

# 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

# 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)

  sudo apt install -y fsverity
  

Next Steps

After installation:

1. Read the User Guide for usage examples
2. Check the TODO List for current development status
3. Review the Changelog for recent updates
4. Join the community for support and contributions