194 lines
No EOL
4.7 KiB
Markdown
194 lines
No EOL
4.7 KiB
Markdown
# 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/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 |