bootc-docs/initramfs-integration.md

# Initramfs Integration for Debian bootc Images

This document explains the essential initramfs integration files required for proper composefs support and boot functionality in Debian bootc images.

## Overview

The initramfs integration provides:
- **Composefs Support**: Enables composefs mounting during early boot
- **Systemd Integration**: Proper systemd service management in initramfs
- **Dracut Module**: Automatic inclusion of bootc setup in initramfs
- **Configuration**: OSTree and composefs configuration

## Required Files

### 1. Systemd Service: `bootc-initramfs-setup.service`

**Location**: `/usr/lib/systemd/system/bootc-initramfs-setup.service`

```ini
[Unit]
DefaultDependencies=no
ConditionKernelCommandLine=composefs
ConditionPathExists=/etc/initrd-release
After=sysroot.mount
Requires=sysroot.mount
Before=initrd-root-fs.target
Before=initrd-switch-root.target
OnFailure=emergency.target
OnFailureJobMode=isolate

[Service]
Type=oneshot
ExecStart=/usr/bin/bootc-initramfs-setup
StandardInput=null
StandardOutput=journal
StandardError=journal+console
RemainAfterExit=yes
```

**Purpose**: 
- Runs during initramfs boot when `composefs` is in kernel command line
- Executes the bootc setup script before root filesystem switch
- Handles composefs-specific initialization

### 2. Dracut Module: `module-setup.sh`

**Location**: `/usr/lib/dracut/modules.d/37composefs/module-setup.sh`

```bash
#!/usr/bin/bash
check() {
    return 0
}

depends() {
    return 0
}

install() {
    inst \
        "${moddir}/bootc-initramfs-setup" /bin/bootc-initramfs-setup
    inst \
        "${moddir}/bootc-initramfs-setup.service" \
        "${systemdsystemunitdir}/bootc-initramfs-setup.service"
    $SYSTEMCTL -q --root "${initdir}" add-wants \
        'initrd-root-fs.target' 'bootc-initramfs-setup.service'
}
```

**Purpose**:
- Dracut module that installs bootc components into initramfs
- Copies the setup script and systemd service
- Adds the service as a dependency of `initrd-root-fs.target`

### 3. OSTree Configuration: `prepare-root.conf`

**Location**: `/usr/lib/ostree-boot/prepare-root.conf`

```ini
[composefs]
enabled = yes

[sysroot]
readonly = true
```

**Purpose**:
- Enables composefs support in OSTree
- Sets sysroot to readonly mode for security
- Configures OSTree to use composefs for root filesystem

## Integration in Containerfile

Add these files to your base image build:

```dockerfile
# Copy initramfs integration files
COPY files/37composefs/bootc-initramfs-setup.service /usr/lib/systemd/system/
COPY files/37composefs/module-setup.sh /usr/lib/dracut/modules.d/37composefs/
COPY files/ostree/prepare-root.conf /usr/lib/ostree-boot/prepare-root.conf

# Make module-setup.sh executable
RUN chmod +x /usr/lib/dracut/modules.d/37composefs/module-setup.sh
```

## Directory Structure

Create this directory structure in your build context:

```
files/
├── 37composefs/
│   ├── bootc-initramfs-setup.service
│   └── module-setup.sh
└── ostree/
    └── prepare-root.conf
```

## Kernel Command Line Requirements

For composefs support, ensure your kernel command line includes:

```
composefs=sha256:...
```

The composefs parameter should point to the composefs image containing your root filesystem.

## Dependencies

These files require:

- **systemd**: For service management
- **dracut**: For initramfs generation
- **ostree**: For composefs support
- **bootc-initramfs-setup**: The actual setup script (provided by bootc)

## Testing

To test initramfs integration:

1. **Build the image** with initramfs files included
2. **Generate initramfs** using dracut
3. **Boot the system** with composefs kernel parameter
4. **Verify** that composefs mounting works correctly

## Troubleshooting

### Common Issues

1. **Service not starting**: Check that `composefs` is in kernel command line
2. **Module not found**: Ensure dracut module is in correct location
3. **Permission denied**: Make sure `module-setup.sh` is executable
4. **Composefs not enabled**: Verify `prepare-root.conf` is in correct location

### Debug Commands

```bash
# Check if service is enabled
systemctl list-unit-files | grep bootc-initramfs-setup

# Verify dracut module
ls -la /usr/lib/dracut/modules.d/37composefs/

# Check composefs configuration
cat /usr/lib/ostree-boot/prepare-root.conf

# Test initramfs generation
dracut --add composefs --force
```

## Source

These files are based on the [debian-bootc project](https://github.com/bootcrew/debian-bootc) which provides Debian-specific bootc integration.

## License

The files are licensed under the GNU Lesser General Public License v2.1 or later, as indicated in the copyright header.