Welcome to developer documentation for leapp-repository!

leapp-repository is a collection of repositories for the Leapp framework (documentation) providing Red Hat Enterprise Linux in-place upgrade functionality.

Important

This documentation is currently under (re)construction and we will appreciate feedback. Feel free to contact us via GH discussion in our upstream project.

Contents:

• Installation and building
  • Building packages locally
    • Use Docker instead of Podman
    • Install locally built packages
  • Public COPR repository
    • Installing builds from the COPR repository
      • Instructions for for non-intel architectures
• Tutorials
  • How to setup the development environment
    • Clone official leapp repositories for IPU
    • Install snactor
    • Register IPU repositories in snactor
  • How to write an Actor for Leapp Upgrade
    • Create the first actor for IPU
      • Most common phases for actors
    • Formulate Your Requirements
    • Scout the Environment
    • Determine Implementation Details
    • Where to Place Your Actors
  • Running a single Actor
    • Running a single actor with minimal context
      • Initial configuration
      • Resolving actor’s message dependencies
      • Limitations
    • Run single actor with existing database
      • Limitations
  • How to create custom content for IPU
    • Create custom repository
    • Create custom actor
    • Naming convention
  • Creating configurable actors
    • Declaring your configuration
    • Accessing configuration values
    • Providing actors with configuration
  • Templates
    • Install a kernel driver during the upgrade
    • Execute custom script during the upgrade
  • Troubleshooting and Debugging
    • Debug logs
    • Troubleshooting with leapp-inspector
      • Usage
    • Debugging Code
    • Inspecting the Target Userspace Container During an Upgrade
    • Debugging Inside Initramfs
  • Dealing with dependencies
    • Packaging and dependencies in leapp-repository
      • Deps packages replacement
    • What to do in leapp-repository when dependencies of leapp change?
    • What to do when leapp-repository dependencies need to change?
• Project structure
  • Leapp data
    • repomap.json - Repomapping
      • Why does leapp need repomapping?
      • repomap.json
      • How leapp determines the target repositories?
    • pes-events.json - PES data
      • Why is PES data necessary for the upgrade?
      • How is PES data processed and used during the upgrade?
    • device_driver_deprecation_data.json (AKA DDDD or HW data)
      • Why is DDDD necessary for the upgrade?
      • Terminology
    • How often are leapp data files updated?
• In-place upgrade architecture and workflow
  • Phases of the Upgrade Workflow
    • Choosing a Phase for an Actor
      • Inhibiting the Upgrade of an Incompatible System
      • Modifying Incompatible Configuration during the Upgrade
    • Phases Overview
      • Old System
      • Interim System
      • Target System
  • Leapp dracut modules and upgrade initramfs
    • Preparing the generation of initramfs
      • Including custom dracut and kernel modules
    • Generating the initramfs
    • Network in initramfs
    • Debugging inside initramfs
  • Target userspace creator
    • Scratch container
      • When we want to modify the source system, but we also don’t want to
      • Target repositories and how are they obtained
      • Broken symbolic links
• Configuring the in-place upgrade
  • Configuring in-place upgrade
    • Environment variables
      • General variables
      • Development variables
  • Experimental features
    • LiveMode
      • Technical details
      • Using the feature
• Libraries and API
  • Deprecated functionality
    • Next release (till TODO date)
    • v0.24.0 (till September 2026)
    • v0.23.0 (till March 2026)
    • v0.20.0 (till September 2024)
    • v0.19.0 (till March 2024)
    • v0.16.0 (till September 2022)
    • v0.15.0 (till April 2022)
    • v0.12.0 (till April 2021)
    • v0.11.0 (till April 2021)
• Contributing
  • Coding guidelines
    • Retrieving information about the source system should be separated from its use
    • Actors need to be unit tested
      • Testing tips
    • Python compatibility
    • Reading environmental variables
    • Running external commands
  • Commits and pull requests (PRs)
    • PR description
    • Commit messages
    • Granularity of commits
    • Create a separate git branch for your changes
  • Community upgrades for Centos-like distros
    • How to contribute
      • Leapp data files
• Frequently Asked Questions
  • Why is the leapp-repository project separated from Leapp?
  • What is an actor and what does it do?
  • When and why do I need to write an actor?
  • What are the best practices for writing actors for in-place upgrades?
  • What are the best practices for creating and adding custom actors for in-place upgrades?
  • What are the requirements for actors to be accepted by upstream?
  • How can I debug my actor? Is there a standard/supported way how to log and get logs from actors/channels?
  • Are there some technical limitations for an actor? Like maximum time execution, …
  • Are there some actions that are either forbidden or not recommended to be done in actors?
  • I got an error about PES data/ Repositories mapping.