Fix YAML linting issues and update system requirements to Debian 13+
- Fix trailing spaces and blank lines in Forgejo workflows - Update system requirements from Ubuntu Jammy/Bookworm to Debian 13+ (Trixie) - Update test treefile to use Debian Trixie instead of Ubuntu Jammy - Update documentation to reflect modern system requirements - Fix yamllint errors for CI/CD functionality - Ensure compatibility with modern OSTree and libapt versions
This commit is contained in:
parent
ec0da91864
commit
3dec23f8f7
85 changed files with 12569 additions and 1088 deletions
427
docs/user-guide.md
Normal file
427
docs/user-guide.md
Normal file
|
|
@ -0,0 +1,427 @@
|
|||
# apt-ostree User Guide
|
||||
|
||||
## System Requirements
|
||||
|
||||
### Supported Operating Systems
|
||||
- Debian 13+ (Trixie) or newer
|
||||
- Ubuntu 25.04+ (Noble Numbat) or newer
|
||||
|
||||
### Required System Components
|
||||
- OSTree 2025.2+
|
||||
- APT 3.0+
|
||||
- Systemd 255+
|
||||
- Polkit 123+
|
||||
|
||||
## Table of Contents
|
||||
1. [Installation](#installation)
|
||||
2. [Basic Setup](#basic-setup)
|
||||
3. [Basic Operations](#basic-operations)
|
||||
4. [Advanced Features](#advanced-features)
|
||||
5. [Troubleshooting](#troubleshooting)
|
||||
6. [Migration Guide](#migration-guide)
|
||||
|
||||
## Installation
|
||||
|
||||
### Prerequisites
|
||||
apt-ostree requires the following system components:
|
||||
- Debian 13+ or Ubuntu 24.04+
|
||||
- OSTree 2025.2+
|
||||
- APT 3.0+
|
||||
- systemd
|
||||
- Polkit
|
||||
- D-Bus
|
||||
|
||||
### Installing from Debian Package
|
||||
```bash
|
||||
# Download and install the package
|
||||
sudo dpkg -i apt-ostree_0.1.0-2_amd64.deb
|
||||
|
||||
# Install dependencies if needed
|
||||
sudo apt-get install -f
|
||||
```
|
||||
|
||||
### Installing from Source
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/robojerk/apt-ostree.git
|
||||
cd apt-ostree
|
||||
|
||||
# Install build dependencies
|
||||
sudo apt-get install build-essential cargo rustc pkg-config \
|
||||
libostree-dev libapt-pkg-dev libpolkit-gobject-1-dev \
|
||||
libdbus-1-dev libsystemd-dev
|
||||
|
||||
# Build and install
|
||||
cargo build --release
|
||||
sudo install -m 755 target/release/apt-ostree /usr/local/bin/
|
||||
sudo install -m 755 target/release/apt-ostreed /usr/local/libexec/
|
||||
```
|
||||
|
||||
## Basic Setup
|
||||
|
||||
### Initial Configuration
|
||||
1. **Create configuration directory:**
|
||||
```bash
|
||||
sudo mkdir -p /etc/apt-ostree
|
||||
```
|
||||
|
||||
2. **Create configuration file:**
|
||||
```bash
|
||||
sudo tee /etc/apt-ostree/config.toml > /dev/null <<EOF
|
||||
[system]
|
||||
data_dir = "/var/lib/apt-ostree"
|
||||
log_level = "info"
|
||||
max_deployments = 3
|
||||
|
||||
[ostree]
|
||||
repo_path = "/ostree/repo"
|
||||
deploy_path = "/ostree/deploy"
|
||||
default_branch = "debian/13/amd64"
|
||||
|
||||
[apt]
|
||||
sources_list = "/etc/apt/sources.list"
|
||||
cache_dir = "/var/cache/apt"
|
||||
|
||||
[security]
|
||||
polkit_enabled = true
|
||||
require_auth = true
|
||||
|
||||
[daemon]
|
||||
user = "root"
|
||||
group = "root"
|
||||
log_file = "/var/log/apt-ostreed.log"
|
||||
EOF
|
||||
```
|
||||
|
||||
3. **Create required directories:**
|
||||
```bash
|
||||
sudo mkdir -p /var/lib/apt-ostree
|
||||
sudo mkdir -p /var/log
|
||||
sudo mkdir -p /var/cache/apt-ostree
|
||||
```
|
||||
|
||||
4. **Set up systemd service:**
|
||||
```bash
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable apt-ostreed
|
||||
sudo systemctl start apt-ostreed
|
||||
```
|
||||
|
||||
### OSTree Repository Setup
|
||||
1. **Initialize OSTree repository:**
|
||||
```bash
|
||||
sudo mkdir -p /ostree/repo
|
||||
sudo ostree init --repo=/ostree/repo --mode=bare
|
||||
```
|
||||
|
||||
2. **Create initial deployment:**
|
||||
```bash
|
||||
sudo apt-ostree deploy debian/13/amd64
|
||||
```
|
||||
|
||||
## Basic Operations
|
||||
|
||||
### Package Management
|
||||
|
||||
#### Installing Packages
|
||||
```bash
|
||||
# Install a single package
|
||||
sudo apt-ostree install nginx
|
||||
|
||||
# Install multiple packages
|
||||
sudo apt-ostree install nginx curl wget
|
||||
|
||||
# Install with specific version
|
||||
sudo apt-ostree install nginx=1.18.0-6
|
||||
```
|
||||
|
||||
#### Removing Packages
|
||||
```bash
|
||||
# Remove a package
|
||||
sudo apt-ostree remove apache2
|
||||
|
||||
# Remove multiple packages
|
||||
sudo apt-ostree remove apache2 mysql-server
|
||||
```
|
||||
|
||||
#### Upgrading Packages
|
||||
```bash
|
||||
# Upgrade all packages
|
||||
sudo apt-ostree upgrade
|
||||
|
||||
# Check for available upgrades
|
||||
sudo apt-ostree status
|
||||
```
|
||||
|
||||
#### Searching Packages
|
||||
```bash
|
||||
# Search for packages
|
||||
sudo apt-ostree search nginx
|
||||
|
||||
# Search with wildcards
|
||||
sudo apt-ostree search "nginx*"
|
||||
```
|
||||
|
||||
### System Management
|
||||
|
||||
#### Deployment Operations
|
||||
```bash
|
||||
# Show current status
|
||||
sudo apt-ostree status
|
||||
|
||||
# List deployments
|
||||
sudo apt-ostree log
|
||||
|
||||
# Rollback to previous deployment
|
||||
sudo apt-ostree rollback
|
||||
|
||||
# Clean up old deployments
|
||||
sudo apt-ostree cleanup
|
||||
```
|
||||
|
||||
#### Kernel Management
|
||||
```bash
|
||||
# View 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=tty0" "console=ttyS0"
|
||||
```
|
||||
|
||||
#### Initramfs Management
|
||||
```bash
|
||||
# Regenerate initramfs
|
||||
sudo apt-ostree initramfs --enable
|
||||
|
||||
# Disable initramfs regeneration
|
||||
sudo apt-ostree initramfs --disable
|
||||
```
|
||||
|
||||
### Transaction Management
|
||||
```bash
|
||||
# Start a transaction
|
||||
sudo apt-ostree transaction start
|
||||
|
||||
# Check transaction status
|
||||
sudo apt-ostree transaction status
|
||||
|
||||
# Commit transaction
|
||||
sudo apt-ostree transaction commit
|
||||
|
||||
# Rollback transaction
|
||||
sudo apt-ostree transaction rollback
|
||||
```
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### Development Commands
|
||||
Development commands are hidden from normal help output but provide useful debugging tools:
|
||||
|
||||
```bash
|
||||
# Run system diagnostics
|
||||
sudo apt-ostree internals diagnostics
|
||||
|
||||
# Validate system state
|
||||
sudo apt-ostree internals validate-state
|
||||
|
||||
# Dump debug information
|
||||
sudo apt-ostree internals debug-dump
|
||||
|
||||
# Execute script in container
|
||||
sudo apt-ostree testutils script-shell /tmp/test.sh --read-only
|
||||
|
||||
# Get system architecture
|
||||
sudo apt-ostree shlib-backend get-basearch
|
||||
```
|
||||
|
||||
### Remote Management
|
||||
```bash
|
||||
# Add remote repository
|
||||
sudo apt-ostree remote add production https://ostree.example.com/repo
|
||||
|
||||
# List remotes
|
||||
sudo apt-ostree remote list
|
||||
|
||||
# Remove remote
|
||||
sudo apt-ostree remote delete production
|
||||
```
|
||||
|
||||
### Branch Management
|
||||
```bash
|
||||
# List available references
|
||||
sudo apt-ostree refs
|
||||
|
||||
# Switch to different branch
|
||||
sudo apt-ostree rebase https://ostree.example.com/repo stable/13/amd64
|
||||
|
||||
# Create new branch
|
||||
sudo apt-ostree refs --create new-branch
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### Daemon Not Running
|
||||
```bash
|
||||
# Check service status
|
||||
sudo systemctl status apt-ostreed
|
||||
|
||||
# Start the service
|
||||
sudo systemctl start apt-ostreed
|
||||
|
||||
# Check logs
|
||||
sudo journalctl -u apt-ostreed -f
|
||||
```
|
||||
|
||||
#### Permission Denied
|
||||
```bash
|
||||
# Check Polkit policies
|
||||
sudo polkit-policy-file-validate /usr/share/polkit-1/actions/org.projectatomic.aptostree1.policy
|
||||
|
||||
# Verify user permissions
|
||||
groups $USER
|
||||
```
|
||||
|
||||
#### OSTree Repository Issues
|
||||
```bash
|
||||
# Check repository status
|
||||
sudo ostree show --repo=/ostree/repo
|
||||
|
||||
# Verify repository integrity
|
||||
sudo ostree fsck --repo=/ostree/repo
|
||||
```
|
||||
|
||||
#### Package Installation Failures
|
||||
```bash
|
||||
# Check APT sources
|
||||
sudo apt-ostree internals diagnostics
|
||||
|
||||
# Verify package availability
|
||||
sudo apt-ostree search <package-name>
|
||||
|
||||
# Check for dependency conflicts
|
||||
sudo apt-ostree info <package-name>
|
||||
```
|
||||
|
||||
### Debug Mode
|
||||
Enable debug logging for troubleshooting:
|
||||
|
||||
```bash
|
||||
# Set debug log level
|
||||
export APT_OSTREE_LOG_LEVEL=debug
|
||||
|
||||
# Run command with verbose output
|
||||
sudo apt-ostree --verbose install nginx
|
||||
```
|
||||
|
||||
### Log Files
|
||||
- **Daemon logs**: `/var/log/apt-ostreed.log`
|
||||
- **System logs**: `sudo journalctl -u apt-ostreed`
|
||||
- **OSTree logs**: `sudo ostree log --repo=/ostree/repo`
|
||||
|
||||
## Migration Guide
|
||||
|
||||
### From Traditional APT
|
||||
1. **Backup current system:**
|
||||
```bash
|
||||
sudo apt-mark showmanual > installed-packages.txt
|
||||
sudo dpkg --get-selections > package-selections.txt
|
||||
```
|
||||
|
||||
2. **Install apt-ostree:**
|
||||
```bash
|
||||
sudo dpkg -i apt-ostree_0.1.0-2_amd64.deb
|
||||
```
|
||||
|
||||
3. **Initialize OSTree repository:**
|
||||
```bash
|
||||
sudo apt-ostree deploy debian/13/amd64
|
||||
```
|
||||
|
||||
4. **Install essential packages:**
|
||||
```bash
|
||||
sudo apt-ostree install $(cat installed-packages.txt)
|
||||
```
|
||||
|
||||
### From rpm-ostree
|
||||
1. **Export package list:**
|
||||
```bash
|
||||
rpm -qa > installed-packages.txt
|
||||
```
|
||||
|
||||
2. **Convert package names (if needed):**
|
||||
```bash
|
||||
# Some package names may differ between RPM and DEB
|
||||
sed 's/^python3-/python3-/g' installed-packages.txt > deb-packages.txt
|
||||
```
|
||||
|
||||
3. **Install with apt-ostree:**
|
||||
```bash
|
||||
sudo apt-ostree install $(cat deb-packages.txt)
|
||||
```
|
||||
|
||||
### Post-Migration
|
||||
1. **Verify system functionality:**
|
||||
```bash
|
||||
sudo apt-ostree internals diagnostics
|
||||
sudo apt-ostree status
|
||||
```
|
||||
|
||||
2. **Test package operations:**
|
||||
```bash
|
||||
sudo apt-ostree search test-package
|
||||
sudo apt-ostree install test-package
|
||||
sudo apt-ostree remove test-package
|
||||
```
|
||||
|
||||
3. **Configure automatic updates:**
|
||||
```bash
|
||||
# Set up cron job for regular upgrades
|
||||
echo "0 2 * * * /usr/bin/apt-ostree upgrade" | sudo crontab -
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### System Administration
|
||||
- **Regular maintenance**: Run `apt-ostree cleanup` periodically
|
||||
- **Backup deployments**: Keep at least 2-3 deployments for rollback
|
||||
- **Monitor logs**: Check daemon logs for errors or warnings
|
||||
- **Test updates**: Test package updates in development environment first
|
||||
|
||||
### Security
|
||||
- **Limit access**: Only authorized users should have access to apt-ostree
|
||||
- **Audit policies**: Regularly review Polkit policies
|
||||
- **Monitor changes**: Log all system changes for audit purposes
|
||||
- **Update regularly**: Keep apt-ostree and system packages updated
|
||||
|
||||
### Performance
|
||||
- **Optimize storage**: Use appropriate filesystem for OSTree repository
|
||||
- **Network optimization**: Use local mirrors for package repositories
|
||||
- **Cache management**: Monitor and clean APT cache regularly
|
||||
- **Resource limits**: Set appropriate limits for daemon processes
|
||||
|
||||
## Support and Resources
|
||||
|
||||
### Documentation
|
||||
- **Manual pages**: `man apt-ostree`, `man apt-ostree-dev`, `man apt-ostree.conf`
|
||||
- **Help system**: `apt-ostree --help`, `apt-ostree <command> --help`
|
||||
- **Online documentation**: Project wiki and documentation
|
||||
|
||||
### Community
|
||||
- **Issue tracker**: GitHub Issues for bug reports
|
||||
- **Discussions**: GitHub Discussions for questions and ideas
|
||||
- **Contributing**: Pull requests and contributions welcome
|
||||
|
||||
### Professional Support
|
||||
For enterprise deployments and professional support, contact the project maintainers.
|
||||
|
||||
---
|
||||
|
||||
*This guide covers the basic usage of apt-ostree. For advanced features and development, refer to the developer documentation and source code.*
|
||||
Loading…
Add table
Add a link
Reference in a new issue