Initial commit: Comprehensive Debian bootc documentation
- Complete documentation for all bootc commands and subcommands - Debian-specific adaptations and workarounds - Manual installation methods to bypass bootc reliability issues - Technical guides with Rust source code analysis - Flowcharts and external command references - Hidden command documentation (bootc internals, state, etc.) - Composefs integration analysis - Base image creation guides (with and without bootc binary) - Management scripts and automation - Comprehensive troubleshooting and examples
This commit is contained in:
robojerk
commit
526f1c1afd
67 changed files with 34174 additions and 0 deletions
243
lint/quick-reference.md
Normal file
243
lint/quick-reference.md
Normal file
|
|
@ -0,0 +1,243 @@
|
|||
# bootc container lint - Quick Reference
|
||||
|
||||
## Command Syntax
|
||||
|
||||
```bash
|
||||
bootc container lint [OPTIONS...]
|
||||
```
|
||||
|
||||
## Common Options
|
||||
|
||||
| Option | Description | Example |
|
||||
|--------|-------------|---------|
|
||||
| `--rootfs` | Specify root filesystem path | `--rootfs /path/to/rootfs` |
|
||||
| `--fatal-warnings` | Treat warnings as fatal errors | `--fatal-warnings` |
|
||||
| `--list` | List all available lints | `--list` |
|
||||
| `--skip` | Skip specific lints | `--skip var-log --skip buildah-injected` |
|
||||
| `--no-truncate` | Show full output (no truncation) | `--no-truncate` |
|
||||
|
||||
## Fatal Lints (Must Pass)
|
||||
|
||||
| Lint | Purpose | Fix |
|
||||
|------|---------|-----|
|
||||
| `var-run` | `/var/run` must be symlink to `/run` | `ln -sf /run /var/run` |
|
||||
| `etc-usretc` | Only `/etc` OR `/usr/etc` (not both) | `rm -rf /usr/etc` |
|
||||
| `bootc-kargs` | Valid kernel args in `/usr/lib/bootc/kargs.d/` | Fix TOML syntax |
|
||||
| `kernel` | Exactly one kernel in `/usr/lib/modules/` | `rm -rf /usr/lib/modules/5.4.0` |
|
||||
| `utf8` | All filenames must be UTF-8 | Rename non-UTF-8 files |
|
||||
| `api-base-directories` | Required dirs: `/dev`, `/proc`, `/sys`, `/run`, `/tmp`, `/var` | `mkdir -p /dev /proc /sys /run /tmp /var` |
|
||||
| `baseimage-root` | Required: `/sysroot`, `/ostree -> sysroot/ostree` | `mkdir -p /sysroot/ostree && ln -sf sysroot/ostree /ostree` |
|
||||
|
||||
## Warning Lints (Recommended)
|
||||
|
||||
| Lint | Purpose | Fix |
|
||||
|------|---------|-----|
|
||||
| `buildah-injected` | No empty `/etc/hostname` or `/etc/resolv.conf` | `rm /etc/hostname /etc/resolv.conf` |
|
||||
| `baseimage-composefs` | Enable composefs in ostree | `echo '[composefs]\nenabled = true' > /usr/lib/ostree/prepare-root.conf` |
|
||||
| `var-log` | No log files in `/var/log` | `rm -rf /var/log/*` |
|
||||
| `var-tmpfiles` | `/var` content needs tmpfiles.d entries | Create `/usr/lib/tmpfiles.d/*.conf` |
|
||||
| `sysusers` | Users/groups need sysusers.d entries | Create `/usr/lib/sysusers.d/*.conf` |
|
||||
| `nonempty-boot` | `/boot` should be empty | `rm -rf /boot/*` |
|
||||
|
||||
## Quick Fixes
|
||||
|
||||
### Fix Common Issues
|
||||
|
||||
```bash
|
||||
# Fix /var/run
|
||||
rm -rf /var/run && ln -sf /run /var/run
|
||||
|
||||
# Fix /usr/etc
|
||||
rm -rf /usr/etc
|
||||
|
||||
# Fix /boot
|
||||
rm -rf /boot/* && mkdir -p /boot
|
||||
|
||||
# Fix log files
|
||||
rm -rf /var/log/*
|
||||
|
||||
# Fix empty files
|
||||
rm -f /etc/hostname /etc/resolv.conf
|
||||
```
|
||||
|
||||
### Create Required Structure
|
||||
|
||||
```bash
|
||||
# API directories
|
||||
mkdir -p /dev /proc /sys /run /tmp /var
|
||||
|
||||
# bootc structure
|
||||
mkdir -p /sysroot/ostree
|
||||
ln -sf sysroot/ostree /ostree
|
||||
|
||||
# Kernel structure
|
||||
mkdir -p /usr/lib/modules/6.1.0
|
||||
echo "kernel" > /usr/lib/modules/6.1.0/vmlinuz
|
||||
|
||||
# Empty /boot
|
||||
mkdir -p /boot
|
||||
```
|
||||
|
||||
## Dockerfile Examples
|
||||
|
||||
### Minimal Working Container
|
||||
|
||||
```dockerfile
|
||||
FROM debian:bookworm-slim
|
||||
|
||||
# Install bootc
|
||||
RUN apt update && apt install -y bootc && apt clean
|
||||
|
||||
# Fix common issues
|
||||
RUN rm -rf /var/run && ln -sf /run /var/run
|
||||
RUN rm -rf /usr/etc
|
||||
RUN rm -rf /boot/* && mkdir -p /boot
|
||||
RUN rm -rf /var/log/*
|
||||
|
||||
# Create required structure
|
||||
RUN mkdir -p /dev /proc /sys /run /tmp /var
|
||||
RUN mkdir -p /sysroot/ostree && ln -sf sysroot/ostree /ostree
|
||||
RUN mkdir -p /usr/lib/modules/6.1.0
|
||||
RUN echo "kernel" > /usr/lib/modules/6.1.0/vmlinuz
|
||||
|
||||
# Lint
|
||||
RUN bootc container lint --fatal-warnings
|
||||
```
|
||||
|
||||
### Complete bootc Image
|
||||
|
||||
```dockerfile
|
||||
FROM debian:bookworm-slim
|
||||
|
||||
# Install dependencies
|
||||
RUN apt update && \
|
||||
apt install -y bootc ostree systemd && \
|
||||
apt clean && \
|
||||
rm -rf /var/lib/apt/lists/*
|
||||
|
||||
# Fix common issues
|
||||
RUN rm -rf /var/run && ln -sf /run /var/run
|
||||
RUN rm -rf /usr/etc
|
||||
RUN rm -rf /boot/* && mkdir -p /boot
|
||||
RUN rm -rf /var/log/*
|
||||
|
||||
# Create required structure
|
||||
RUN mkdir -p /dev /proc /sys /run /tmp /var
|
||||
RUN mkdir -p /sysroot/ostree && ln -sf sysroot/ostree /ostree
|
||||
RUN mkdir -p /usr/lib/modules/6.1.0
|
||||
RUN echo "kernel" > /usr/lib/modules/6.1.0/vmlinuz
|
||||
|
||||
# Configure composefs
|
||||
RUN mkdir -p /usr/lib/ostree && \
|
||||
echo '[composefs]\nenabled = true' > /usr/lib/ostree/prepare-root.conf
|
||||
|
||||
# Configure kernel args
|
||||
RUN mkdir -p /usr/lib/bootc/kargs.d && \
|
||||
echo '[kargs]\nappend = ["console=ttyS0", "quiet"]' > /usr/lib/bootc/kargs.d/99-console.toml
|
||||
|
||||
# Lint
|
||||
RUN bootc container lint --fatal-warnings
|
||||
```
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
```yaml
|
||||
- name: Lint bootc container
|
||||
run: podman run --rm ${{ matrix.image }} bootc container lint --fatal-warnings
|
||||
```
|
||||
|
||||
### GitLab CI
|
||||
|
||||
```yaml
|
||||
lint:
|
||||
script:
|
||||
- podman run --rm $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA bootc container lint --fatal-warnings
|
||||
```
|
||||
|
||||
### Jenkins
|
||||
|
||||
```groovy
|
||||
stage('Lint') {
|
||||
steps {
|
||||
sh 'podman run --rm my-image bootc container lint --fatal-warnings'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Common Commands
|
||||
|
||||
```bash
|
||||
# Basic lint
|
||||
bootc container lint
|
||||
|
||||
# Lint with warnings as fatal
|
||||
bootc container lint --fatal-warnings
|
||||
|
||||
# Lint specific rootfs
|
||||
bootc container lint --rootfs /path/to/rootfs
|
||||
|
||||
# Skip specific lints
|
||||
bootc container lint --skip var-log --skip buildah-injected
|
||||
|
||||
# Show all issues
|
||||
bootc container lint --no-truncate
|
||||
|
||||
# List available lints
|
||||
bootc container lint --list
|
||||
|
||||
# Debug mode
|
||||
RUST_LOG=debug bootc container lint
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Errors
|
||||
|
||||
| Error | Cause | Fix |
|
||||
|-------|-------|-----|
|
||||
| `Not a symlink: var/run` | `/var/run` is directory | `ln -sf /run /var/run` |
|
||||
| `Found /usr/etc` | Both `/etc` and `/usr/etc` exist | `rm -rf /usr/etc` |
|
||||
| `Multiple kernels found` | Multiple kernel versions | Keep only one |
|
||||
| `Found non-utf8 filename` | Non-UTF-8 filenames | Rename files |
|
||||
| `Missing API filesystem base directory` | Missing required dirs | `mkdir -p /dev /proc /sys /run /tmp /var` |
|
||||
|
||||
### Debug Commands
|
||||
|
||||
```bash
|
||||
# Check container structure
|
||||
podman run --rm -it my-image bash
|
||||
ls -la /var/run
|
||||
ls -la /etc /usr/etc
|
||||
ls -la /usr/lib/modules/
|
||||
ls -la /boot
|
||||
|
||||
# Test specific lints
|
||||
bootc container lint --skip utf8 --skip var-log
|
||||
|
||||
# Show full output
|
||||
bootc container lint --no-truncate
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Run lint early** in build process
|
||||
2. **Use `--fatal-warnings`** in CI/CD
|
||||
3. **Fix issues immediately** when found
|
||||
4. **Test with actual bootc installation**
|
||||
5. **Use minimal base images**
|
||||
6. **Clean up package caches**
|
||||
7. **Avoid creating log files**
|
||||
8. **Use symlinks for `/var/run`**
|
||||
|
||||
## File Locations
|
||||
|
||||
| Purpose | Location |
|
||||
|---------|----------|
|
||||
| Kernel args | `/usr/lib/bootc/kargs.d/*.toml` |
|
||||
| Composefs config | `/usr/lib/ostree/prepare-root.conf` |
|
||||
| Sysusers config | `/usr/lib/sysusers.d/*.conf` |
|
||||
| Tmpfiles config | `/usr/lib/tmpfiles.d/*.conf` |
|
||||
| Kernel files | `/usr/lib/modules/$kver/vmlinuz` |
|
||||
| Initramfs | `/usr/lib/modules/$kver/initramfs.img` |
|
||||
Loading…
Add table
Add a link
Reference in a new issue