deb-bootc-image-builder-new/docs/fedora-kickstart.md

# Fedora Kickstart Approach for Bootc Installation

## Overview

Fedora uses a sophisticated kickstart-based approach for bootc installation that is fundamentally different from traditional package-based installations. The key insight is that **bootc installations are container-first, not package-first**.

## Key Technical Concepts

### 1. The `ostreecontainer` Directive

The `ostreecontainer` kickstart directive is the core mechanism for bootc installation:

```kickstart
ostreecontainer --url quay.io/centos-bootc/centos-bootc:stream9
```

**Key characteristics:**
- **No `%packages` section** - the entire system is container-based
- **Registry URL** specifies the container image to install
- **Authentication** handled separately via registry configuration
- **Partitioning** still required, but no package management

### 1.1. Complete `ostreecontainer` Parameters

Based on analysis of the Fedora COSMIC Atomic ISO, the full parameter set is:

```kickstart
ostreecontainer --url="quay.io/exampleos/foo:latest" \
                --stateroot="default" \
                --remote="default" \
                --transport="registry" \
                --no-signature-verification
```

**Parameter details:**
- **`--url`** (required): Container image URL (e.g., `quay.io/exampleos/foo:latest`)
- **`--stateroot`**: Name for the state directory (default: `default`)
- **`--remote`**: Name of the OSTree remote (default: same as stateroot)
- **`--transport`**: Transport method (default: `registry`)
- **`--no-signature-verification`**: Disable signature verification (optional)

### 1.2. Implementation Details

**Python-based implementation** in PyKickstart:
- **File**: `/usr/lib/python3.13/site-packages/pykickstart/commands/ostreecontainer.py`
- **Class**: `F38_OSTreeContainer` (available in Fedora 38+)
- **Conflicts**: Cannot be used with `ostreesetup` directive
- **Experimental**: Marked as experimental in documentation

### 2. Kickstart Infrastructure

Based on analysis of the Fedora COSMIC Atomic ISO, the kickstart system includes:

#### 2.1. Dracut Hooks
- **`50-kickstart-genrules.sh`**: Generates udev rules for fetching kickstarts
- **`11-fetch-kickstart-net.sh`**: Fetches kickstart files from network
- **`26-parse-anaconda-kickstart.sh`**: Handles kickstart command line parsing

#### 2.2. Anaconda Integration
- **PyKickstart library**: Python-based kickstart parsing
- **Command handlers**: Including `ostreecontainer` and `ostreesetup`
- **Version support**: Fedora 38+ includes `ostreecontainer` support

#### 2.3. Kickstart Fetching Methods
- **Network**: HTTP, HTTPS, FTP, NFS
- **Local**: CDROM, hard disk
- **Multiple URLs**: Support for fallback kickstart locations

### 3. Registry Authentication

Fedora handles registry access through kickstart `%pre` sections:

#### Basic Authentication
```kickstart
%pre
mkdir -p /etc/ostree
cat > /etc/ostree/auth.json << 'EOF'
{
        "auths": {
                "quay.io": {
                        "auth": "<your secret here>"
                }
        }
}
EOF
%end
```

#### Insecure Registry Support
```kickstart
%pre
mkdir -p /etc/containers/registries.conf.d/
cat > /etc/containers/registries.conf.d/local-registry.conf << 'EOF'
[[registry]]
location="[IP_Address]:5000"
insecure=true
EOF
%end
```

### 4. Complete Kickstart Example

```kickstart
# Basic setup
text
network --bootproto=dhcp --device=link --activate

# Basic partitioning
clearpart --all --initlabel --disklabel=gpt
reqpart --add-boot
part / --grow --fstype xfs

# Container installation - NO %packages section!
ostreecontainer --url quay.io/centos-bootc/centos-bootc:stream9

# System configuration
firewall --disabled
services --enabled=sshd
rootpw --iscrypted locked
sshkey --username root "<your key here>"
reboot
```

## Installation Methods Analysis

### Fedora COSMIC Atomic vs Fedora CoreOS

**Key Discovery**: Different Fedora variants use different approaches:

| Variant | Configuration System | Container Support | Use Case |
|---------|---------------------|-------------------|----------|
| **Fedora COSMIC Atomic** | Kickstart + `ostreecontainer` | Native | Traditional server/workstation |
| **Fedora CoreOS** | Ignition | Native | Container-first, immutable |
| **Fedora Server/Workstation** | Kickstart + `ostreecontainer` | Native | Traditional Linux |

## Three Installation Methods

### 1. Stock Anaconda ISO/PXE (Network-based)
- Uses standard Fedora installer with custom kickstart
- Requires network access during installation
- Container image fetched from registry
- **Advantage**: Uses existing installer infrastructure
- **Disadvantage**: Requires network connectivity

### 2. Custom Installer ISO (bootc-image-builder generated)
- Uses `anaconda-iso` type in bootc-image-builder
- Container image **embedded in the ISO**
- No network access needed during installation
- **Advantage**: Air-gapped installation possible
- **Disadvantage**: Larger ISO size

### 3. Direct Container Installation (`bootc install`)
- Uses `bootc install to-disk` or `bootc install to-filesystem`
- Container image is the "source of truth"
- Can be run from any Linux environment
- **Advantage**: Most flexible, container-native
- **Disadvantage**: Requires existing Linux environment

## Technical Implementation Details

### Container Runtime Requirements
- **Podman** or **containerd** must be available in installer environment
- **Registry access** configured via `/etc/containers/registries.conf.d/`
- **Authentication** handled via `/etc/ostree/auth.json`

### Partitioning Strategy
- **GPT partition table** required
- **Boot partition** for EFI/BIOS boot
- **Root partition** for container installation
- **No package management** - all content from container

### Network Configuration
- **DHCP** for basic network access
- **Registry connectivity** for container pull
- **Optional**: Static IP configuration

## Implications for Debian Implementation

### Calamares Integration
1. **Custom module needed** to handle `ostreecontainer` equivalent
2. **Registry authentication** must be implemented
3. **Container runtime** must be available
4. **Partitioning** handled before container installation

### debian-installer Integration
1. **Preseed extension** needed for container support
2. **Container runtime** added to installer environment
3. **Registry configuration** in installer
4. **Major architectural change** from package-based to container-based

### Key Differences from Traditional Installation
- **No package management** during installation
- **Container-first** approach
- **Registry authentication** required
- **Partitioning** still needed but simpler
- **System configuration** via kickstart/preseed

## Registry Handling Patterns

### Authentication Methods
1. **Username/password** via auth.json
2. **Token-based** authentication
3. **Certificate-based** authentication
4. **Insecure registry** support for development

### Configuration Locations
- **`/etc/ostree/auth.json`** - authentication credentials
- **`/etc/containers/registries.conf.d/`** - registry configuration
- **`/etc/pki/ca-trust/source/anchors/`** - certificate authorities

## Security Considerations

### Registry Security
- **TLS verification** by default
- **Insecure registries** only for development
- **Certificate management** for custom CAs
- **Authentication** required for private registries

### Container Security
- **Image verification** via signatures
- **Content trust** mechanisms
- **Runtime security** via container runtime

## Advantages of This Approach

1. **Container-native** - aligns with modern deployment patterns
2. **Atomic updates** - via ostree/bootc upgrade
3. **Immutable systems** - reduces configuration drift
4. **Registry integration** - leverages existing container infrastructure
5. **Air-gapped support** - via embedded ISO approach

## Challenges for Debian

1. **Preseed lacks `ostreecontainer` equivalent** - major technical hurdle
2. **Container runtime** not standard in debian-installer
3. **Registry authentication** not built into installer
4. **Architectural shift** from package-based to container-based
5. **Tooling gaps** - need custom modules/extensions

## Real-World Implementation Analysis

### Fedora COSMIC Atomic ISO Structure
```
Fedora-COSMIC-Atomic-ostree-x86_64-42-1.1.iso
├── boot/grub2/grub.cfg          # BIOS boot configuration
├── EFI/BOOT/grub.cfg            # EFI boot configuration
├── images/
│   ├── install.img              # Anaconda installer image
│   ├── pxeboot/
│   │   ├── initrd.img           # XZ-compressed initrd
│   │   └── vmlinuz              # Kernel
│   └── eltorito.img             # El Torito boot image
└── Fedora-Legal-README.txt      # Legal information
```

### Kickstart Processing Pipeline
1. **Boot**: Kernel loads with kickstart parameters
2. **Dracut**: Hooks process kickstart fetching
3. **Anaconda**: PyKickstart parses configuration
4. **Installation**: `ostreecontainer` directive triggers container installation
5. **Configuration**: System setup via kickstart commands

### Key Implementation Files
- **`ostreecontainer.py`**: Core directive implementation
- **`f42.py`**: Fedora 42 handler with `ostreecontainer` support
- **Dracut hooks**: Network and disk kickstart fetching
- **Anaconda modules**: Integration with installer

## Next Steps for Implementation

1. **Study `ostreecontainer` implementation** in Anaconda
2. **Design Calamares module** for container installation
3. **Extend preseed** for container support
4. **Implement registry handling** in both approaches
5. **Test container installation** workflows
6. **Choose approach**: Kickstart (traditional) vs Ignition (modern)

## References

- [Fedora bootc bare metal installation guide](https://docs.fedoraproject.org/en-US/bootc/bare-metal/)
- [Kickstart ostreecontainer documentation](https://pykickstart.readthedocs.io/en/latest/kickstart-docs.html#ostreecontainer)
- [bootc-image-builder documentation](https://github.com/osbuild/bootc-image-builder)
- [bib-kickstart-demo repository](https://github.com/osbuild/bib-kickstart-demo)