# 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