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:

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.
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.

Overview

Andaman

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

GitHub: https://github.com/FyraLabs/anda (opens in a new tab)
Devdocs: https://developer.fyralabs.com/andaman (opens in a new tab)
Fyra Wiki Page: https://wiki.fyralabs.com/Andaman (opens in a new tab)

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.

GitHub: https://github.com/FyraLabs/anda (opens in a new tab)
Devdocs: https://developer.fyralabs.com/terra/autoupdate (opens in a new tab)
Rhai playground: https://rhai.rs/playground/stable/ (opens in a new tab)

Builder

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.

GitHub: https://github.com/terrapkg/builder (opens in a new tab)

Madoguchi

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).

GitHub: https://github.com/terrapkg/packages (opens in a new tab)
Devdocs: you are here
Fyra Wiki Page: https://wiki.fyralabs.com/Terra (opens in a new tab)

Subatomic

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.

GitHub: https://github.com/FyraLabs/subatomic (opens in a new tab)
URL: https://subatomic.fyralabs.com (opens in a new tab)
API Interactive Docs: https://subatomic.fyralabs.com/docs/index.html (opens in a new tab)

Tetsudou

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

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

When dnf/dnf5 Needs a Terra Package

It fetches a metalink (opens in a new tab) XML file from Tetsudou, which
- finds the repository's mirror information: https://github.com/terrapkg/tetsudou/tree/main/repos (opens in a new tab)
- uses numerous algorithms to determine which repository will be the fastest for that client
- fetches the hashes/timestamps for the repomd.xml file, which is in the mirror generated by Subatomic
Client fetches repodata from a mirror
Client downloads RPM packages from the mirror
Client installs them

FAQ Installing