bootc-docs/bootc-base-imagectl.md

# bootc-base-imagectl

A core premise of the bootc model is that rich
control over Linux system customization can be accomplished
with a "default" container build:

```
FROM <base image>
RUN ...
```

As of recently, it is possible to e.g. swap the kernel
and other fundamental components as part of default derivation.

However, some use cases want even more control - for example,
as an organization deploying a bootc system, I may want to ensure
the base image version carries a set of packages at
exactly specific versions (perhaps defined by a lockfile,
or an rpm-md repository). There are many tools which
manage snapshots of yum (rpm-md) repositories.

There are currently issues where it won't quite work to e.g.
`dnf -y upgrade selinux-policy-targeted`.

The `/usr/libexec/bootc-base-imagectl` tool which is
included in the base image is designed to enable building
a root filesystem in ostree-container format from a set
of RPMs controlled by the user.

## Architecture Overview

The `bootc-base-imagectl` tool is a Python script that provides three main operations:

1. **`build-rootfs`** - Generate a container root filesystem from RPM packages
2. **`rechunk`** - Split container images into reproducible, chunked layers  
3. **`list`** - Enumerate available build configurations

The tool uses `rpm-ostree` under the hood to compose root filesystems from RPM packages,
with support for custom manifests, package locking, and reproducible builds.

## Understanding the base image content

Most, but not all content from the base image comes from RPMs.
There is some additional non-RPM content, as well as postprocessing
that operates on the filesystem root. At the current time the
implementation of the base image build uses `rpm-ostree`,
but this is considered an implementation detail subject to change.

## Using bootc-base-imagectl build-rootfs

The core operation is `bootc-base-imagectl build-rootfs`.

### Basic Usage

```bash
bootc-base-imagectl build-rootfs [OPTIONS] <source_root> <target>
```

**Required Arguments:**
- `source_root` - Path to source root with `/etc/yum.repos.d` configuration
- `target` - Path where the root filesystem will be generated (must not exist)

### Advanced Options

```bash
bootc-base-imagectl build-rootfs \
  --manifest=minimal \
  --install=package1 --install=package2 \
  --add-dir=/path/to/overlay1 --add-dir=/path/to/overlay2 \
  --lock=package-1.0.0-1.x86_64 \
  --no-docs \
  --sysusers \
  --cachedir=/var/cache/dnf \
  --repo=fedora --repo=updates \
  /source/root /target/rootfs
```

**Key Options:**
- `--manifest` - Select build configuration (default: "default")
- `--install` - Add additional packages to install
- `--add-dir` - Copy directory contents as overlay layers
- `--lock` - Lock packages to specific versions (NEVRA or NEVR format)
- `--no-docs` - Skip documentation packages
- `--sysusers` - Use systemd-sysusers instead of hardcoded passwd/group
- `--cachedir` - Cache repository metadata and RPMs
- `--repo` - Enable specific repositories only
- `--reinject` - Copy build configurations into target

### Technical Implementation

The tool performs these steps:

1. **Repository Setup**: Runs `dnf repolist` to refresh repository metadata
2. **Manifest Processing**: Loads YAML manifest from `/usr/share/doc/bootc-base-imagectl/manifests/`
3. **Override Generation**: Creates temporary JSON with user overrides
4. **OSTree Compose**: Executes `rpm-ostree compose rootfs` with the manifest
5. **Post-processing**: Fixes permissions and runs `bootc container lint`
6. **Cleanup**: Removes temporary files and repositories

## Using bootc-base-imagectl rechunk

This operation is strongly related to `build-rootfs` but is also orthogonal;
it can be used on a "regular" container build as well.

### Basic Usage

```bash
bootc-base-imagectl rechunk [OPTIONS] <from_image> <to_image>
```

**Required Arguments:**
- `from_image` - Source image in container storage (e.g., `quay.io/exampleos:build`)
- `to_image` - Output image in container storage (e.g., `quay.io/exampleos:latest`)

### Advanced Options

```bash
bootc-base-imagectl rechunk \
  --max-layers=10 \
  quay.io/exampleos:build \
  quay.io/exampleos:latest
```

**Options:**
- `--max-layers` - Configure maximum number of output layers

### Container Usage

This command assumes it will be run as a container image, and defaults
to wanting write access to the container storage.

```bash
podman run --rm --privileged \
  -v /var/lib/containers:/var/lib/containers \
  quay.io/fedora/fedora-bootc:rawhide \
  bootc-base-imagectl rechunk \
  quay.io/exampleos/exampleos:build \
  quay.io/exampleos/exampleos:latest
```

### Technical Implementation

The rechunk operation uses `rpm-ostree experimental compose build-chunked-oci`:

1. **Input Processing**: Reads the source container image
2. **Layer Analysis**: Analyzes RPM database to determine optimal layer splits
3. **Chunking**: Splits content into separate, reproducible layers
4. **Timestamp Canonicalization**: Sets all timestamps to zero for reproducibility
5. **Output Generation**: Creates new container image with chunked layers

### Rationale

When performing a complex container derivation, there are several issues:

#### Replaced duplicate content

When e.g. upgrading or replacing the kernel or other large packages
as part of a container build (without squashing all layers) then
the old replaced content will still be present.

#### Removed content still present

Similarly, `RUN dnf -y remove` etc. will still retain that removed
content in prior layers.

#### Timestamp drift

By default, many tools will use the current timestamp when writing
files. `rpm` will do this (unless `SOURCE_DATE_EPOCH` is set), and
other tools like `cp` and `curl` will as well.

This means that every build of the image will produce a new
tar stream (with new timestamps) - that will get pushed to a registry
and downloaded by clients, even if the content didn't actually change.

### What rechunk does: split reproducible chunked images

The `bootc-base-imagectl rechunk` command fixes all of these issues
by taking an input container, operates on its final merged filesystem
tree (hence removed/overridden files are handled), and then splits it up
(currently based on the RPM database) into separate layers (tarballs).

Further, because bootc uses OSTree today, and OSTree canonializes all timestamps
to zero on the client side, this tool does that at build time.

## Using bootc-base-imagectl list

The `list` command enumerates available build configurations that can be selected by passing `--manifest` to `build-rootfs`.

### Usage

```bash
bootc-base-imagectl list
```

### Output Format

```
minimal: Minimal bootc base image
default: Standard bootc base image with common packages
server: Server-focused bootc base image
---
```

### Technical Implementation

The list command:

1. **Manifest Discovery**: Scans `/usr/share/doc/bootc-base-imagectl/manifests/` for `.yaml` files
2. **Filtering**: Excludes `.hidden.yaml` files and symbolic links
3. **Metadata Extraction**: Uses `rpm-ostree compose tree --print-only` to read manifest metadata
4. **Summary Display**: Shows manifest name and description from metadata

## Technical Implementation Details

### Core Architecture

The `bootc-base-imagectl` tool is implemented as a Python 3 script that orchestrates `rpm-ostree` operations. The tool provides a high-level interface for:

- **Manifest Management**: Loading and processing YAML treefiles
- **Package Resolution**: Handling RPM dependencies and version locking
- **Overlay Support**: Managing additional content layers
- **Reproducible Builds**: Ensuring consistent output across builds

### Key Components

#### 1. Manifest System
- **Location**: `/usr/share/doc/bootc-base-imagectl/manifests/`
- **Format**: YAML treefiles compatible with `rpm-ostree`
- **Discovery**: Automatic scanning for `.yaml` files (excluding `.hidden.yaml`)
- **Override Support**: JSON overrides for user customizations

#### 2. Package Management
- **Repository Handling**: Uses `/etc/yum.repos.d` configuration from source root
- **Version Locking**: Supports NEVRA (Name-Epoch-Version-Release-Architecture) format
- **Dependency Resolution**: Leverages `rpm-ostree`'s advanced dependency solver
- **Caching**: Optional repository metadata and RPM caching

#### 3. Overlay System
- **Directory Overlays**: Copy additional content as OSTree overlay layers
- **Temporary Repositories**: Create temporary OSTree repos for overlay content
- **Content Integration**: Merge overlay content into final rootfs

#### 4. Build Process
```python
# Simplified build flow
def run_build_rootfs(args):
    # 1. Repository refresh
    subprocess.check_call(['dnf', 'repolist'], stdout=subprocess.DEVNULL)
    
    # 2. Manifest processing
    manifest_path = find_manifest(args.manifest)
    
    # 3. Override generation
    if user_overrides:
        create_temp_override_manifest(overrides)
    
    # 4. OSTree compose
    subprocess.run(['rpm-ostree', 'compose', 'rootfs', ...])
    
    # 5. Post-processing
    fix_permissions(target)
    subprocess.run(['bootc', 'container', 'lint', f'--rootfs={target}'])
```

### External Dependencies

The tool requires these external commands:
- `rpm-ostree` - Core OSTree composition engine
- `dnf` - Package manager for repository operations
- `ostree` - OSTree repository management
- `bootc` - Container validation and linting

### Error Handling

The implementation includes comprehensive error handling:
- **Subprocess Failures**: Captures and reports command execution errors
- **File Operations**: Handles temporary file creation and cleanup
- **Repository Issues**: Manages OSTree repository lifecycle
- **Validation**: Runs `bootc container lint` to ensure output validity

### Security Considerations

- **Temporary Files**: All temporary files are created with secure permissions
- **Repository Isolation**: Uses separate temporary OSTree repositories for overlays
- **Content Validation**: Validates all input manifests and configurations
- **Cleanup**: Ensures all temporary resources are properly cleaned up

### Cross builds and the builder image

The build tooling is designed to support "cross builds"; the
repository root could e.g. be CentOS Stream 10, while the
builder root is Fedora or RHEL, etc.

In other words, one given base image can be used as a "builder" to produce another
using different RPMs.

## Practical Examples

### Example 1: Generate a new image using CentOS Stream 10 content from RHEL

```dockerfile
FROM quay.io/centos/centos:stream10 as repos

FROM registry.redhat.io/rhel10/rhel-bootc:10 as builder
RUN --mount=type=bind,from=repos,src=/,dst=/repos,rw \
    /usr/libexec/bootc-base-imagectl build-rootfs \
    --manifest=minimal \
    /repos /target-rootfs

# This container image uses the "artifact pattern"; it has some
# basic configuration we expect to apply to multiple container images.
FROM quay.io/exampleos/baseconfig@sha256:.... as baseconfig

FROM scratch
COPY --from=builder /target-rootfs/ /
# Now we make other arbitrary changes. Copy our systemd units and
# other tweaks from the baseconfig container image.
COPY --from=baseconfig /usr/ /usr/
RUN <<EORUN
set -xeuo pipefail
# Install critical components
dnf -y install linux-firmware NetworkManager cloud-init cowsay
dnf clean all
bootc container lint
EORUN
LABEL containers.bootc 1
ENV container=oci
STOPSIGNAL SIGRTMIN+3
CMD ["/sbin/init"]
```

### Example 2: Custom package selection with version locking

```dockerfile
FROM quay.io/fedora/fedora-bootc:rawhide as builder

# Create custom repository configuration
RUN mkdir -p /custom-repos/etc/yum.repos.d
COPY custom-repos.repo /custom-repos/etc/yum.repos.d/

# Build rootfs with specific packages and versions
RUN /usr/libexec/bootc-base-imagectl build-rootfs \
    --manifest=minimal \
    --install=kernel \
    --install=systemd \
    --lock=kernel-6.5.0-1.fc39.x86_64 \
    --lock=systemd-253-1.fc39.x86_64 \
    --cachedir=/var/cache/dnf \
    /custom-repos /target-rootfs

FROM scratch
COPY --from=builder /target-rootfs/ /
LABEL containers.bootc 1
ENV container=oci
STOPSIGNAL SIGRTMIN+3
CMD ["/sbin/init"]
```

### Example 3: Adding custom overlay content

```dockerfile
FROM quay.io/fedora/fedora-bootc:rawhide as builder

# Prepare custom overlay content
RUN mkdir -p /overlay/usr/local/bin
RUN echo '#!/bin/bash\necho "Hello from custom overlay!"' > /overlay/usr/local/bin/custom-script
RUN chmod +x /overlay/usr/local/bin/custom-script

# Build rootfs with overlay
RUN /usr/libexec/bootc-base-imagectl build-rootfs \
    --manifest=default \
    --add-dir=/overlay \
    --install=cowsay \
    / /target-rootfs

FROM scratch
COPY --from=builder /target-rootfs/ /
LABEL containers.bootc 1
ENV container=oci
STOPSIGNAL SIGRTMIN+3
CMD ["/sbin/init"]
```

### Example 4: Reproducible build with rechunking

```dockerfile
# Build stage
FROM quay.io/fedora/fedora-bootc:rawhide as builder
RUN /usr/libexec/bootc-base-imagectl build-rootfs \
    --manifest=minimal \
    --install=kernel \
    --install=systemd \
    / /target-rootfs

# Create intermediate image
FROM scratch as intermediate
COPY --from=builder /target-rootfs/ /
LABEL containers.bootc 1
ENV container=oci
STOPSIGNAL SIGRTMIN+3
CMD ["/sbin/init"]

# Rechunk for reproducibility
FROM quay.io/fedora/fedora-bootc:rawhide as rechunker
COPY --from=intermediate / /
RUN /usr/libexec/bootc-base-imagectl rechunk \
    --max-layers=5 \
    localhost/intermediate:latest \
    localhost/final:latest

# Final image
FROM localhost/final:latest