bootc-docs/lint/examples-and-troubleshooting.md

# bootc container lint - Examples and Troubleshooting

## Practical Examples

### 1. Basic Container Image Linting

#### Minimal Working Example

```dockerfile
FROM debian:bookworm-slim

# Install bootc
RUN apt update && apt install -y bootc && apt clean

# Create required API directories
RUN mkdir -p /dev /proc /sys /run /tmp /var

# Create proper /var/run symlink
RUN ln -sf /run /var/run

# Create /sysroot and /ostree structure
RUN mkdir -p /sysroot/ostree && ln -sf sysroot/ostree /ostree

# Create kernel structure
RUN mkdir -p /usr/lib/modules/6.1.0 && \
    echo "kernel" > /usr/lib/modules/6.1.0/vmlinuz

# Create empty /boot directory
RUN mkdir -p /boot

# Lint the container
RUN bootc container lint
```

#### Common Issues and Fixes

**Issue**: `/var/run` is a directory instead of symlink
```bash
# Problem
mkdir -p /var/run

# Fix
rm -rf /var/run
ln -sf /run /var/run
```

**Issue**: Both `/etc` and `/usr/etc` exist
```bash
# Problem
mkdir -p /etc /usr/etc

# Fix (choose one)
rm -rf /usr/etc  # Keep /etc
# OR
rm -rf /etc      # Keep /usr/etc (not recommended)
```

**Issue**: Multiple kernels present
```bash
# Problem
mkdir -p /usr/lib/modules/5.4.0 /usr/lib/modules/6.1.0

# Fix
rm -rf /usr/lib/modules/5.4.0  # Keep only one
```

### 2. Advanced Container Configuration

#### Complete bootc-compatible Image

```dockerfile
FROM debian:bookworm-slim

# Install bootc and dependencies
RUN apt update && \
    apt install -y bootc ostree systemd && \
    apt clean && \
    rm -rf /var/lib/apt/lists/*

# Create required API directories
RUN mkdir -p /dev /proc /sys /run /tmp /var

# Fix /var/run symlink
RUN ln -sf /run /var/run

# Create bootc-specific structure
RUN mkdir -p /sysroot/ostree && \
    ln -sf sysroot/ostree /ostree

# Create kernel structure
RUN mkdir -p /usr/lib/modules/6.1.0 && \
    echo "kernel" > /usr/lib/modules/6.1.0/vmlinuz && \
    echo "initramfs" > /usr/lib/modules/6.1.0/initramfs.img

# Create empty /boot directory
RUN mkdir -p /boot

# Configure composefs
RUN mkdir -p /usr/lib/ostree && \
    echo '[composefs]\nenabled = true' > /usr/lib/ostree/prepare-root.conf

# Configure kernel arguments
RUN mkdir -p /usr/lib/bootc/kargs.d && \
    echo '[kargs]\nappend = ["console=ttyS0", "quiet"]' > /usr/lib/bootc/kargs.d/99-console.toml

# Create systemd sysusers.d entries
RUN mkdir -p /usr/lib/sysusers.d && \
    echo 'u app 1000 "Application User"' > /usr/lib/sysusers.d/app.conf

# Create tmpfiles.d entries
RUN mkdir -p /usr/lib/tmpfiles.d && \
    echo 'd /var/log/app 0755 app app -' > /usr/lib/tmpfiles.d/app.conf

# Lint the container
RUN bootc container lint --fatal-warnings
```

### 3. CI/CD Integration Examples

#### GitHub Actions

```yaml
name: Build and Lint bootc Image

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build-and-lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Build container image
        run: |
          podman build --tag my-bootc-image .
      
      - name: Lint container image
        run: |
          podman run --rm my-bootc-image bootc container lint --fatal-warnings
      
      - name: Test installation
        run: |
          podman run --rm --privileged my-bootc-image bootc install to-disk /dev/loop0
```

#### GitLab CI

```yaml
stages:
  - build
  - lint
  - test

build:
  stage: build
  script:
    - podman build --tag $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA .
    - podman push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA

lint:
  stage: lint
  script:
    - podman run --rm $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA bootc container lint --fatal-warnings

test:
  stage: test
  script:
    - podman run --rm --privileged $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA bootc install to-disk /dev/loop0
```

#### Jenkins Pipeline

```groovy
pipeline {
    agent any
    
    stages {
        stage('Build') {
            steps {
                sh 'podman build --tag my-bootc-image .'
            }
        }
        
        stage('Lint') {
            steps {
                sh 'podman run --rm my-bootc-image bootc container lint --fatal-warnings'
            }
        }
        
        stage('Test') {
            steps {
                sh 'podman run --rm --privileged my-bootc-image bootc install to-disk /dev/loop0'
            }
        }
    }
}
```

### 4. Development Workflow Examples

#### Pre-commit Hook

```bash
#!/bin/bash
# .git/hooks/pre-commit

echo "Running bootc container lint..."

# Build the image
podman build --tag temp-bootc-image . || exit 1

# Run lint
podman run --rm temp-bootc-image bootc container lint --fatal-warnings || {
    echo "Lint failed. Please fix issues before committing."
    podman rmi temp-bootc-image
    exit 1
}

# Clean up
podman rmi temp-bootc-image
echo "Lint passed!"
```

#### Makefile Integration

```makefile
.PHONY: build lint test clean

IMAGE_NAME = my-bootc-image
IMAGE_TAG = latest

build:
	podman build --tag $(IMAGE_NAME):$(IMAGE_TAG) .

lint: build
	podman run --rm $(IMAGE_NAME):$(IMAGE_TAG) bootc container lint --fatal-warnings

test: lint
	podman run --rm --privileged $(IMAGE_NAME):$(IMAGE_TAG) bootc install to-disk /dev/loop0

clean:
	podman rmi $(IMAGE_NAME):$(IMAGE_TAG) || true

all: test
```

#### Docker Compose

```yaml
version: '3.8'

services:
  build:
    build: .
    image: my-bootc-image:latest
    
  lint:
    image: my-bootc-image:latest
    command: bootc container lint --fatal-warnings
    depends_on:
      - build
      
  test:
    image: my-bootc-image:latest
    command: bootc install to-disk /dev/loop0
    privileged: true
    depends_on:
      - lint
```

## Troubleshooting Guide

### 1. Common Error Messages

#### "Failed lint: var-run: Not a symlink: var/run"

**Problem**: `/var/run` exists as a directory instead of symlink
**Solution**:
```bash
# Remove directory and create symlink
rm -rf /var/run
ln -sf /run /var/run
```

**Dockerfile Fix**:
```dockerfile
RUN rm -rf /var/run && ln -sf /run /var/run
```

#### "Failed lint: etc-usretc: Found /usr/etc - this is a bootc implementation detail"

**Problem**: Both `/etc` and `/usr/etc` exist
**Solution**:
```bash
# Choose one approach
rm -rf /usr/etc  # Keep /etc (recommended)
# OR
rm -rf /etc      # Keep /usr/etc (not recommended)
```

**Dockerfile Fix**:
```dockerfile
RUN rm -rf /usr/etc  # Keep /etc only
```

#### "Failed lint: kernel: Multiple kernels found"

**Problem**: Multiple kernel versions present
**Solution**:
```bash
# Keep only one kernel version
rm -rf /usr/lib/modules/5.4.0
# Keep /usr/lib/modules/6.1.0
```

**Dockerfile Fix**:
```dockerfile
RUN rm -rf /usr/lib/modules/5.4.0  # Keep only 6.1.0
```

#### "Failed lint: utf8: Found non-utf8 filename"

**Problem**: Files with non-UTF-8 names
**Solution**:
```bash
# Find and rename problematic files
find / -name "*" -print0 | xargs -0 -I {} sh -c 'echo "Checking: {}"'
# Rename files with non-UTF-8 names
```

**Prevention**:
```dockerfile
# Use UTF-8 locale
ENV LANG=C.UTF-8
ENV LC_ALL=C.UTF-8
```

#### "Failed lint: api-base-directories: Missing API filesystem base directory"

**Problem**: Required directories missing
**Solution**:
```bash
# Create all required directories
mkdir -p /dev /proc /sys /run /tmp /var
```

**Dockerfile Fix**:
```dockerfile
RUN mkdir -p /dev /proc /sys /run /tmp /var
```

### 2. Warning Messages

#### "Lint warning: buildah-injected: /etc/hostname is an empty file"

**Problem**: Empty files injected by build system
**Solution**:
```bash
# Remove empty files or add content
rm /etc/hostname
# OR
echo "myhostname" > /etc/hostname
```

**Dockerfile Fix**:
```dockerfile
RUN rm -f /etc/hostname /etc/resolv.conf
```

#### "Lint warning: var-log: Found non-empty logfiles"

**Problem**: Log files in container image
**Solution**:
```bash
# Remove log files
rm -rf /var/log/*
# OR create symlinks to /dev/null
ln -sf /dev/null /var/log/app.log
```

**Dockerfile Fix**:
```dockerfile
RUN rm -rf /var/log/* && \
    mkdir -p /var/log && \
    ln -sf /dev/null /var/log/app.log
```

#### "Lint warning: nonempty-boot: Found non-empty /boot"

**Problem**: Content in `/boot` directory
**Solution**:
```bash
# Remove content from /boot
rm -rf /boot/*
# Keep /boot empty
```

**Dockerfile Fix**:
```dockerfile
RUN rm -rf /boot/* && mkdir -p /boot
```

### 3. Debugging Techniques

#### Enable Debug Output

```bash
# Enable detailed logging
RUST_LOG=debug bootc container lint

# Show all issues without truncation
bootc container lint --no-truncate

# List all available lints
bootc container lint --list
```

#### Test Specific Lints

```bash
# Test only fatal lints
bootc container lint --skip var-log --skip buildah-injected --skip baseimage-composefs --skip var-tmpfiles --skip sysusers --skip nonempty-boot

# Test only warning lints
bootc container lint --skip var-run --skip etc-usretc --skip bootc-kargs --skip kernel --skip utf8 --skip api-base-directories --skip baseimage-root
```

#### Inspect Container Structure

```bash
# Explore container filesystem
podman run --rm -it my-image bash

# Check specific directories
ls -la /var/run
ls -la /etc /usr/etc
ls -la /usr/lib/modules/
ls -la /boot
```

### 4. Performance Optimization

#### Skip Expensive Lints During Development

```bash
# Skip recursive UTF-8 check during development
bootc container lint --skip utf8

# Skip all warning lints
bootc container lint --skip var-log --skip buildah-injected --skip baseimage-composefs --skip var-tmpfiles --skip sysusers --skip nonempty-boot
```

#### Use Faster Base Images

```dockerfile
# Use minimal base image
FROM debian:bookworm-slim

# Avoid unnecessary packages
RUN apt update && \
    apt install -y --no-install-recommends bootc && \
    apt clean && \
    rm -rf /var/lib/apt/lists/*
```

### 5. Integration Issues

#### Container Runtime Compatibility

**Problem**: Lint fails in different container runtime
**Solution**:
```bash
# Use podman (recommended)
podman run --rm my-image bootc container lint

# Use docker with proper flags
docker run --rm my-image bootc container lint
```

#### Build Context Issues

**Problem**: Lint fails due to build context
**Solution**:
```dockerfile
# Ensure proper working directory
WORKDIR /

# Copy files explicitly
COPY . /workspace
WORKDIR /workspace
```

#### Permission Issues

**Problem**: Permission denied errors
**Solution**:
```bash
# Run with proper permissions
podman run --rm --user root my-image bootc container lint

# Or fix permissions in container
RUN chmod -R 755 /usr/lib/bootc
```

### 6. Advanced Troubleshooting

#### Custom Lint Configuration

```bash
# Create custom lint script
#!/bin/bash
set -e

echo "Running custom lint checks..."

# Run specific lints
bootc container lint --skip utf8 --skip var-log

# Additional custom checks
if [ -f /etc/hostname ]; then
    echo "Warning: /etc/hostname should not exist in container"
fi

echo "Custom lint checks passed!"
```

#### Lint Result Analysis

```bash
# Capture lint output for analysis
bootc container lint --no-truncate > lint-results.txt 2>&1

# Analyze results
grep "Failed lint" lint-results.txt
grep "Lint warning" lint-results.txt
```

#### Automated Fixes

```bash
#!/bin/bash
# Auto-fix common issues

echo "Fixing common bootc lint issues..."

# Fix /var/run
if [ -d /var/run ] && [ ! -L /var/run ]; then
    echo "Fixing /var/run symlink..."
    rm -rf /var/run
    ln -sf /run /var/run
fi

# Fix /usr/etc
if [ -d /usr/etc ] && [ -d /etc ]; then
    echo "Removing /usr/etc (keeping /etc)..."
    rm -rf /usr/etc
fi

# Fix /boot
if [ -d /boot ] && [ "$(ls -A /boot)" ]; then
    echo "Clearing /boot directory..."
    rm -rf /boot/*
fi

# Fix log files
if [ -d /var/log ] && [ "$(ls -A /var/log)" ]; then
    echo "Clearing log files..."
    rm -rf /var/log/*
fi

echo "Auto-fix completed!"
```

This comprehensive examples and troubleshooting guide provides practical solutions for common bootc lint issues and integration patterns.