How Terra Works

This document outlines the process of how a package ends up to the end users.

Terra Installation

There are two ways to install Terra:

  1. By installing the terra-release package (recommended). This makes sure your Terra installation won't break even if we have any server migrations, infrastructure changes, etc.
  2. With .repo files. We provide .repo files at https://github.com/terrapkg/subatomic-repos (opens in a new tab).

This document assumes Terra is installed via the first method. You should also look at the "Last updated on" footnote (above the next page button; a feature of Nextra that you can see on all pages) because things might change over time.



Also known as anda, a package build toolchain in Rust, designed to simplify building various package types.

Anda internally calls Mock (opens in a new tab) and rpmbuild to build RPM packages.

AndaX (update.rhai)

A scripting language based on Rhai (opens in a new tab) specifically made for writing update scripts.


CI images for Terra CI operations. They are based on the Fedora minimal Docker images, with tools installed so we don't have to install them inside CI. Basically an image with preinstalled CI tools for our specific use.


API for handling Terra-related queries, recording build failures/successes, spec location in the git repo, and redirecting Repology links to the monorepo.

Monorepo for Terra Sources

A monorepo hosted on GitHub with all the packages sources, including .spec files, update scripts (update.rhais), anda.hcls, etc. If you want to submit package requess, go to this repository (since it's the main issue tracker).


A modern package delivery system for RPMs. It generates repodata and manages package uploads. subatomic-cli is the command line tool used to upload the packages.


A metalink generator, so the clients (dnf/dnf5) knows what mirrors a repo has and which ones are preferred.

When CI Builds a New Package

  1. The autobuild.yml workflow detects for changes in commits
  2. In the manifest stage, anda ci finds out what directories have been changed in the last commit
  3. A matrix of jobs will run for each architecture and each package
  4. GitHub Actions fetches the Terra builders
  5. It runs anda build with the Terra mock files
  6. It uploads built SRPMs and RPMs to Subatomic only if the build is successful and it's not in a pull request
  7. It notifies Madoguchi for a successful/failed build

When dnf/dnf5 Needs a Terra Package

  1. It fetches a metalink (opens in a new tab) XML file from Tetsudou, which
  2. Client fetches repodata from a mirror
  3. Client downloads RPM packages from the mirror
  4. Client installs them