Initial commit: apt-ostree project with 100% rpm-ostree CLI compatibility
This commit is contained in:
robojerk
commit
a48ad95d70
81 changed files with 28515 additions and 0 deletions
475
docs/user-guide/getting-started.md
Normal file
475
docs/user-guide/getting-started.md
Normal file
|
|
@ -0,0 +1,475 @@
|
|||
# Getting Started with apt-ostree
|
||||
|
||||
## Introduction
|
||||
|
||||
apt-ostree is a Debian/Ubuntu equivalent of rpm-ostree that provides atomic, immutable system updates with APT package management. This guide will help you get started with apt-ostree.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### System Requirements
|
||||
- **Operating System**: Debian/Ubuntu-based system with OSTree support
|
||||
- **Architecture**: x86_64 (other architectures may work but are not fully tested)
|
||||
- **Memory**: 2GB RAM minimum, 4GB+ recommended
|
||||
- **Disk Space**: 10GB+ free space for OSTree repository
|
||||
|
||||
### Required Software
|
||||
- OSTree (version 2023.1 or later)
|
||||
- APT package manager
|
||||
- systemd
|
||||
- D-Bus
|
||||
|
||||
## Installation
|
||||
|
||||
### Install apt-ostree
|
||||
|
||||
#### From Source
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone <repository-url>
|
||||
cd apt-ostree
|
||||
|
||||
# Build the project
|
||||
cargo build --release
|
||||
|
||||
# Install binaries
|
||||
sudo cp target/release/apt-ostree /usr/bin/
|
||||
sudo cp target/release/apt-ostreed /usr/bin/
|
||||
```
|
||||
|
||||
#### Install System Components
|
||||
```bash
|
||||
# Install service files
|
||||
sudo cp src/daemon/apt-ostreed.service /etc/systemd/system/
|
||||
sudo cp src/daemon/apt-ostree-bootstatus.service /etc/systemd/system/
|
||||
|
||||
# Install D-Bus policy
|
||||
sudo cp src/daemon/org.aptostree.dev.conf /etc/dbus-1/system.d/
|
||||
|
||||
# Enable and start services
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable apt-ostreed
|
||||
sudo systemctl start apt-ostreed
|
||||
```
|
||||
|
||||
### Verify Installation
|
||||
```bash
|
||||
# Check if apt-ostree is installed
|
||||
apt-ostree --version
|
||||
|
||||
# Check daemon status
|
||||
sudo systemctl status apt-ostreed
|
||||
|
||||
# Test daemon communication
|
||||
apt-ostree daemon-ping
|
||||
```
|
||||
|
||||
## Basic Usage
|
||||
|
||||
### Check System Status
|
||||
```bash
|
||||
# Show current system status
|
||||
apt-ostree status
|
||||
|
||||
# Show status in JSON format
|
||||
apt-ostree status --json
|
||||
|
||||
# Show verbose status
|
||||
apt-ostree status --verbose
|
||||
```
|
||||
|
||||
### Initialize System
|
||||
```bash
|
||||
# Initialize apt-ostree system
|
||||
sudo apt-ostree init
|
||||
|
||||
# Initialize with specific branch
|
||||
sudo apt-ostree init --branch debian/stable/x86_64
|
||||
```
|
||||
|
||||
### Install Packages
|
||||
```bash
|
||||
# Install a single package
|
||||
sudo apt-ostree install curl
|
||||
|
||||
# Install multiple packages
|
||||
sudo apt-ostree install curl vim git
|
||||
|
||||
# Install with dry-run (preview changes)
|
||||
sudo apt-ostree install --dry-run curl
|
||||
|
||||
# Install with automatic confirmation
|
||||
sudo apt-ostree install --yes curl
|
||||
```
|
||||
|
||||
### Upgrade System
|
||||
```bash
|
||||
# Upgrade system packages
|
||||
sudo apt-ostree upgrade
|
||||
|
||||
# Upgrade with preview
|
||||
sudo apt-ostree upgrade --preview
|
||||
|
||||
# Upgrade with check mode
|
||||
sudo apt-ostree upgrade --check
|
||||
|
||||
# Upgrade with automatic reboot
|
||||
sudo apt-ostree upgrade --reboot
|
||||
```
|
||||
|
||||
### Rollback Changes
|
||||
```bash
|
||||
# Rollback to previous deployment
|
||||
sudo apt-ostree rollback
|
||||
|
||||
# Rollback with dry-run
|
||||
sudo apt-ostree rollback --dry-run
|
||||
|
||||
# Rollback with reboot
|
||||
sudo apt-ostree rollback --reboot
|
||||
```
|
||||
|
||||
### Search and Information
|
||||
```bash
|
||||
# Search for packages
|
||||
apt-ostree search "web server"
|
||||
|
||||
# Search with JSON output
|
||||
apt-ostree search --json "web server"
|
||||
|
||||
# Show package information
|
||||
apt-ostree info nginx
|
||||
|
||||
# List installed packages
|
||||
apt-ostree list
|
||||
```
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### Package Management
|
||||
|
||||
#### Install Packages with Options
|
||||
```bash
|
||||
# Install packages with specific options
|
||||
sudo apt-ostree install --allow-downgrade package1 package2
|
||||
|
||||
# Install packages with dry-run
|
||||
sudo apt-ostree install --dry-run --verbose package1 package2
|
||||
```
|
||||
|
||||
#### Remove Packages
|
||||
```bash
|
||||
# Remove packages
|
||||
sudo apt-ostree remove package1 package2
|
||||
|
||||
# Remove with dry-run
|
||||
sudo apt-ostree remove --dry-run package1
|
||||
```
|
||||
|
||||
#### Override Packages
|
||||
```bash
|
||||
# Replace package in base
|
||||
sudo apt-ostree override replace package1=version1
|
||||
|
||||
# Remove package from base
|
||||
sudo apt-ostree override remove package1
|
||||
|
||||
# List current overrides
|
||||
apt-ostree override list
|
||||
|
||||
# Reset all overrides
|
||||
sudo apt-ostree override reset
|
||||
```
|
||||
|
||||
### System Management
|
||||
|
||||
#### Deploy Different Branches
|
||||
```bash
|
||||
# Deploy to different branch
|
||||
sudo apt-ostree deploy debian/testing/x86_64
|
||||
|
||||
# Deploy with reboot
|
||||
sudo apt-ostree deploy --reboot debian/testing/x86_64
|
||||
```
|
||||
|
||||
#### Rebase to Different Tree
|
||||
```bash
|
||||
# Rebase to different tree
|
||||
sudo apt-ostree rebase debian/testing/x86_64
|
||||
|
||||
# Rebase with reboot
|
||||
sudo apt-ostree rebase --reboot debian/testing/x86_64
|
||||
```
|
||||
|
||||
#### Cleanup Old Deployments
|
||||
```bash
|
||||
# Cleanup old deployments
|
||||
sudo apt-ostree cleanup
|
||||
|
||||
# Cleanup keeping specific number
|
||||
sudo apt-ostree cleanup --keep 3
|
||||
```
|
||||
|
||||
### Kernel and Boot Management
|
||||
|
||||
#### Manage Kernel Arguments
|
||||
```bash
|
||||
# Show current kernel arguments
|
||||
sudo apt-ostree kargs
|
||||
|
||||
# Add kernel argument
|
||||
sudo apt-ostree kargs --append=console=ttyS0
|
||||
|
||||
# Remove kernel argument
|
||||
sudo apt-ostree kargs --delete=console=ttyS0
|
||||
|
||||
# Replace kernel argument
|
||||
sudo apt-ostree kargs --replace=console=ttyS0,115200
|
||||
```
|
||||
|
||||
#### Manage Initramfs
|
||||
```bash
|
||||
# Regenerate initramfs
|
||||
sudo apt-ostree initramfs --regenerate
|
||||
|
||||
# Manage initramfs files
|
||||
sudo apt-ostree initramfs-etc --track /etc/crypttab
|
||||
sudo apt-ostree initramfs-etc --untrack /etc/crypttab
|
||||
```
|
||||
|
||||
### Database Operations
|
||||
|
||||
#### Query Package Database
|
||||
```bash
|
||||
# Show package changes between commits
|
||||
apt-ostree db diff commit1 commit2
|
||||
|
||||
# List packages in commit
|
||||
apt-ostree db list commit1
|
||||
|
||||
# Show database version
|
||||
apt-ostree db version
|
||||
```
|
||||
|
||||
#### Refresh Metadata
|
||||
```bash
|
||||
# Refresh repository metadata
|
||||
sudo apt-ostree refresh-md
|
||||
|
||||
# Reload configuration
|
||||
sudo apt-ostree reload
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables
|
||||
```bash
|
||||
# Set log level
|
||||
export RUST_LOG=debug
|
||||
|
||||
# Set OSTree repository path
|
||||
export OSTREE_REPO_PATH=/path/to/repo
|
||||
|
||||
# Set APT cache directory
|
||||
export APT_CACHE_DIR=/path/to/cache
|
||||
```
|
||||
|
||||
### Configuration Files
|
||||
```bash
|
||||
# Main configuration file
|
||||
/etc/apt-ostree/config.toml
|
||||
|
||||
# Daemon configuration
|
||||
/etc/apt-ostree/daemon.toml
|
||||
|
||||
# Repository configuration
|
||||
/etc/apt-ostree/repos.d/
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### Permission Errors
|
||||
```bash
|
||||
# Check if running as root
|
||||
sudo apt-ostree status
|
||||
|
||||
# Check file permissions
|
||||
ls -la /var/lib/apt-ostree/
|
||||
```
|
||||
|
||||
#### Daemon Issues
|
||||
```bash
|
||||
# Check daemon status
|
||||
sudo systemctl status apt-ostreed
|
||||
|
||||
# Restart daemon
|
||||
sudo systemctl restart apt-ostreed
|
||||
|
||||
# View daemon logs
|
||||
sudo journalctl -u apt-ostreed -f
|
||||
```
|
||||
|
||||
#### OSTree Issues
|
||||
```bash
|
||||
# Check OSTree status
|
||||
ostree status
|
||||
|
||||
# Check OSTree repository
|
||||
ostree log debian/stable/x86_64
|
||||
|
||||
# Repair OSTree repository
|
||||
ostree fsck
|
||||
```
|
||||
|
||||
#### Package Issues
|
||||
```bash
|
||||
# Update package lists
|
||||
sudo apt update
|
||||
|
||||
# Check package availability
|
||||
apt-ostree search package-name
|
||||
|
||||
# Check package dependencies
|
||||
apt-ostree info package-name
|
||||
```
|
||||
|
||||
### Debug Information
|
||||
```bash
|
||||
# Enable debug logging
|
||||
RUST_LOG=debug apt-ostree status
|
||||
|
||||
# Show verbose output
|
||||
apt-ostree status --verbose
|
||||
|
||||
# Show system information
|
||||
apt-ostree status --json | jq '.system'
|
||||
```
|
||||
|
||||
### Recovery Procedures
|
||||
|
||||
#### Rollback Failed Update
|
||||
```bash
|
||||
# Rollback to previous deployment
|
||||
sudo apt-ostree rollback
|
||||
|
||||
# Rollback with reboot
|
||||
sudo apt-ostree rollback --reboot
|
||||
```
|
||||
|
||||
#### Reset System State
|
||||
```bash
|
||||
# Reset all user modifications
|
||||
sudo apt-ostree reset
|
||||
|
||||
# Reset with reboot
|
||||
sudo apt-ostree reset --reboot
|
||||
```
|
||||
|
||||
#### Emergency Recovery
|
||||
```bash
|
||||
# Boot into emergency mode
|
||||
# Edit bootloader to boot previous deployment
|
||||
|
||||
# Or use OSTree directly
|
||||
ostree admin rollback
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### System Updates
|
||||
1. **Always preview changes**: Use `--preview` or `--dry-run` before applying changes
|
||||
2. **Keep multiple deployments**: Use `cleanup --keep 3` to maintain rollback options
|
||||
3. **Test in staging**: Test updates in a staging environment before production
|
||||
4. **Monitor system**: Check system status regularly with `apt-ostree status`
|
||||
|
||||
### Package Management
|
||||
1. **Use atomic operations**: Install multiple packages in single transaction
|
||||
2. **Verify packages**: Check package information before installation
|
||||
3. **Manage dependencies**: Let apt-ostree handle dependency resolution
|
||||
4. **Use overrides sparingly**: Only override packages when necessary
|
||||
|
||||
### Security
|
||||
1. **Keep system updated**: Regular security updates
|
||||
2. **Monitor logs**: Check system logs for issues
|
||||
3. **Use sandboxing**: Scripts run in sandboxed environment
|
||||
4. **Verify signatures**: Package signatures are verified automatically
|
||||
|
||||
### Performance
|
||||
1. **Optimize storage**: Regular cleanup of old deployments
|
||||
2. **Use caching**: APT cache is maintained for performance
|
||||
3. **Monitor resources**: Check disk and memory usage
|
||||
4. **Batch operations**: Combine multiple operations when possible
|
||||
|
||||
## Examples
|
||||
|
||||
### Basic System Setup
|
||||
```bash
|
||||
# Initialize system
|
||||
sudo apt-ostree init
|
||||
|
||||
# Install essential packages
|
||||
sudo apt-ostree install curl vim git
|
||||
|
||||
# Check status
|
||||
apt-ostree status
|
||||
```
|
||||
|
||||
### Development Environment
|
||||
```bash
|
||||
# Install development tools
|
||||
sudo apt-ostree install build-essential git vim
|
||||
|
||||
# Install specific version
|
||||
sudo apt-ostree override replace gcc=4:9.3.0-1ubuntu2
|
||||
|
||||
# Check overrides
|
||||
apt-ostree override list
|
||||
```
|
||||
|
||||
### Server Setup
|
||||
```bash
|
||||
# Install web server
|
||||
sudo apt-ostree install nginx
|
||||
|
||||
# Configure kernel arguments
|
||||
sudo apt-ostree kargs --append=console=ttyS0,115200
|
||||
|
||||
# Regenerate initramfs
|
||||
sudo apt-ostree initramfs --regenerate
|
||||
|
||||
# Reboot to apply changes
|
||||
sudo apt-ostree upgrade --reboot
|
||||
```
|
||||
|
||||
### System Maintenance
|
||||
```bash
|
||||
# Check system status
|
||||
apt-ostree status
|
||||
|
||||
# Update system
|
||||
sudo apt-ostree upgrade --preview
|
||||
|
||||
# Apply updates
|
||||
sudo apt-ostree upgrade
|
||||
|
||||
# Cleanup old deployments
|
||||
sudo apt-ostree cleanup --keep 3
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
### Learn More
|
||||
- Read the [Architecture Documentation](architecture/overview.md)
|
||||
- Explore [Advanced Usage](advanced-usage.md)
|
||||
- Check [Troubleshooting Guide](troubleshooting.md)
|
||||
|
||||
### Get Help
|
||||
- Check system logs: `sudo journalctl -u apt-ostreed`
|
||||
- Enable debug logging: `RUST_LOG=debug apt-ostree status`
|
||||
- Review documentation in `/usr/share/doc/apt-ostree/`
|
||||
|
||||
### Contribute
|
||||
- Report bugs and issues
|
||||
- Contribute code and documentation
|
||||
- Help with testing and validation
|
||||
Loading…
Add table
Add a link
Reference in a new issue