feat: Complete Phase 7.3 Advanced Features
Some checks failed
Debian Forge CI/CD Pipeline / Build and Test (push) Successful in 1m48s
Debian Forge CI/CD Pipeline / Security Audit (push) Failing after 6s
Debian Forge CI/CD Pipeline / Package Validation (push) Successful in 1m44s
Debian Forge CI/CD Pipeline / Status Report (push) Has been skipped
Some checks failed
Debian Forge CI/CD Pipeline / Build and Test (push) Successful in 1m48s
Debian Forge CI/CD Pipeline / Security Audit (push) Failing after 6s
Debian Forge CI/CD Pipeline / Package Validation (push) Successful in 1m44s
Debian Forge CI/CD Pipeline / Status Report (push) Has been skipped
- Enhanced APT stage with advanced features:
- Package version pinning and holds
- Custom repository priorities
- Specific version installation
- Updated schemas for all new options
- New dependency resolution stage (org.osbuild.apt.depsolve):
- Advanced dependency solving with conflict resolution
- Multiple strategies (conservative, aggressive, resolve)
- Package optimization and dry-run support
- New Docker/OCI image building stage (org.osbuild.docker):
- Docker and OCI container image creation
- Flexible configuration for entrypoints, commands, env vars
- Image export and multi-format support
- New cloud image generation stage (org.osbuild.cloud):
- Multi-cloud support (AWS, GCP, Azure, OpenStack, DigitalOcean)
- Cloud-init integration and provider-specific metadata
- Live ISO and network boot image creation
- New debug and developer tools stage (org.osbuild.debug):
- Debug logging and manifest validation
- Performance profiling and dependency tracing
- Comprehensive debug reports
- Example manifests for all new features:
- debian-advanced-apt.json - Advanced APT features
- debian-docker-container.json - Container image building
- debian-aws-image.json - AWS cloud image
- debian-live-iso.json - Live ISO creation
- debian-debug-build.json - Debug mode
- Updated .gitignore with comprehensive artifact patterns
- All tests passing with 292 passed, 198 skipped
- Phase 7.3 marked as completed in todo.txt
debian-forge is now production-ready with advanced features! 🎉
This commit is contained in:
Joe
parent
acc3f7c9be
commit
7c724dd149
30 changed files with 4657 additions and 256 deletions
299
docs/debian-image-building-tutorial.md
Normal file
299
docs/debian-image-building-tutorial.md
Normal file
|
|
@ -0,0 +1,299 @@
|
|||
# Debian Image Building Tutorial
|
||||
|
||||
This tutorial will guide you through building Debian images using `debian-forge`, a Debian-specific fork of OSBuild with full APT support.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- `debian-forge` installed (see [Installation Guide](installation.md))
|
||||
- Basic understanding of Debian package management
|
||||
- Familiarity with JSON manifest format
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Basic Debian Image
|
||||
|
||||
Let's start with a simple Debian Trixie minimal image:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "2",
|
||||
"pipelines": [
|
||||
{
|
||||
"runner": "org.osbuild.linux",
|
||||
"name": "build",
|
||||
"stages": [
|
||||
{
|
||||
"type": "org.osbuild.debootstrap",
|
||||
"options": {
|
||||
"suite": "trixie",
|
||||
"mirror": "http://deb.debian.org/debian",
|
||||
"arch": "amd64",
|
||||
"variant": "minbase"
|
||||
}
|
||||
},
|
||||
{
|
||||
"type": "org.osbuild.apt",
|
||||
"options": {
|
||||
"packages": ["linux-image-amd64", "systemd", "openssh-server"]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Save this as `debian-minimal.json` and build it:
|
||||
|
||||
```bash
|
||||
python3 -m osbuild debian-minimal.json --output-dir ./output --libdir .
|
||||
```
|
||||
|
||||
### 2. Server Image with Custom Packages
|
||||
|
||||
For a server image, we'll add more packages and configuration:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "2",
|
||||
"pipelines": [
|
||||
{
|
||||
"runner": "org.osbuild.linux",
|
||||
"name": "build",
|
||||
"stages": [
|
||||
{
|
||||
"type": "org.osbuild.debootstrap",
|
||||
"options": {
|
||||
"suite": "trixie",
|
||||
"mirror": "http://deb.debian.org/debian",
|
||||
"arch": "amd64",
|
||||
"variant": "minbase",
|
||||
"extra_packages": ["apt", "systemd", "bash"]
|
||||
}
|
||||
},
|
||||
{
|
||||
"type": "org.osbuild.apt.config",
|
||||
"options": {
|
||||
"sources": {
|
||||
"debian": "deb http://deb.debian.org/debian trixie main\n"
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"type": "org.osbuild.apt",
|
||||
"options": {
|
||||
"packages": [
|
||||
"linux-image-amd64",
|
||||
"systemd",
|
||||
"openssh-server",
|
||||
"nginx",
|
||||
"mysql-server",
|
||||
"python3",
|
||||
"curl",
|
||||
"vim",
|
||||
"htop"
|
||||
],
|
||||
"recommends": false,
|
||||
"update": true
|
||||
}
|
||||
},
|
||||
{
|
||||
"type": "org.osbuild.hostname",
|
||||
"options": {
|
||||
"hostname": "debian-server"
|
||||
}
|
||||
},
|
||||
{
|
||||
"type": "org.osbuild.systemd",
|
||||
"options": {
|
||||
"enabled_services": [
|
||||
"sshd",
|
||||
"systemd-networkd",
|
||||
"systemd-resolved",
|
||||
"nginx",
|
||||
"mysql"
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Ubuntu Image
|
||||
|
||||
Building Ubuntu images is similar, just change the suite and mirror:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "2",
|
||||
"pipelines": [
|
||||
{
|
||||
"runner": "org.osbuild.linux",
|
||||
"name": "build",
|
||||
"stages": [
|
||||
{
|
||||
"type": "org.osbuild.debootstrap",
|
||||
"options": {
|
||||
"suite": "jammy",
|
||||
"mirror": "http://archive.ubuntu.com/ubuntu",
|
||||
"arch": "amd64",
|
||||
"variant": "minbase"
|
||||
}
|
||||
},
|
||||
{
|
||||
"type": "org.osbuild.apt.config",
|
||||
"options": {
|
||||
"sources": {
|
||||
"ubuntu": "deb http://archive.ubuntu.com/ubuntu jammy main restricted universe multiverse\n"
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"type": "org.osbuild.apt",
|
||||
"options": {
|
||||
"packages": [
|
||||
"linux-image-generic",
|
||||
"systemd",
|
||||
"openssh-server",
|
||||
"curl",
|
||||
"vim"
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### Custom Repositories
|
||||
|
||||
Add custom repositories for additional packages:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "org.osbuild.apt.config",
|
||||
"options": {
|
||||
"sources": {
|
||||
"debian": "deb http://deb.debian.org/debian trixie main\n",
|
||||
"debian-forge": "deb https://git.raines.xyz/api/packages/particle-os/debian trixie main\n"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Package Preferences
|
||||
|
||||
Configure package pinning and preferences:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "org.osbuild.apt.config",
|
||||
"options": {
|
||||
"preferences": {
|
||||
"debian-forge": "Package: *\nPin: origin git.raines.xyz\nPin-Priority: 1000\n"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Cross-Architecture Builds
|
||||
|
||||
Build for different architectures:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "org.osbuild.debootstrap",
|
||||
"options": {
|
||||
"suite": "trixie",
|
||||
"mirror": "http://deb.debian.org/debian",
|
||||
"arch": "arm64",
|
||||
"variant": "minbase"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### APT Proxy
|
||||
|
||||
Use apt-cacher-ng for faster builds:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "org.osbuild.apt",
|
||||
"options": {
|
||||
"packages": ["linux-image-amd64"],
|
||||
"apt_proxy": "http://localhost:3142"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Package Selection
|
||||
|
||||
- Use `recommends: false` to avoid installing unnecessary packages
|
||||
- Include only essential packages in the base image
|
||||
- Use `extra_packages` in debootstrap for core system packages
|
||||
|
||||
### 2. Repository Configuration
|
||||
|
||||
- Always configure APT sources explicitly
|
||||
- Use HTTPS mirrors when available
|
||||
- Consider using apt-cacher-ng for faster builds
|
||||
|
||||
### 3. Service Configuration
|
||||
|
||||
- Enable only necessary services
|
||||
- Use systemd for service management
|
||||
- Configure hostname and network settings
|
||||
|
||||
### 4. Security
|
||||
|
||||
- Keep packages updated
|
||||
- Use minimal base images
|
||||
- Configure firewall rules appropriately
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Package not found**: Check package name and availability
|
||||
2. **Repository errors**: Verify mirror URL and suite name
|
||||
3. **Architecture issues**: Ensure target architecture is supported
|
||||
4. **Network issues**: Use apt-cacher-ng proxy
|
||||
|
||||
### Debug Mode
|
||||
|
||||
Use the `--break` option to debug specific stages:
|
||||
|
||||
```bash
|
||||
python3 -m osbuild manifest.json --break org.osbuild.apt
|
||||
```
|
||||
|
||||
### Logs
|
||||
|
||||
Check build logs for detailed information:
|
||||
|
||||
```bash
|
||||
python3 -m osbuild manifest.json --json | jq '.log'
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
See the [example manifests](../test/data/manifests/debian/) for more complete examples:
|
||||
|
||||
- `debian-trixie-minimal.json` - Minimal Debian Trixie image
|
||||
- `ubuntu-jammy-server.json` - Ubuntu Jammy server image
|
||||
- `debian-atomic-container.json` - Debian Atomic container image
|
||||
- `debian-trixie-arm64.json` - ARM64 cross-architecture build
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [APT Stages Reference](apt-stages.md)
|
||||
- [Container Image Building](container-image-building.md)
|
||||
- [Cloud Image Generation](cloud-image-generation.md)
|
||||
- [Performance Optimization](performance-optimization.md)
|
||||
Loading…
Add table
Add a link
Reference in a new issue