# 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` |