Quickstart

This quickstart guide provides the first steps to get Fatbuildr up and ready!

Installation

Deb (Debian, Ubuntu)

First download packages repository signing key:

# curl -sS https://pkgs.rackslab.io/keyring.asc | gpg --dearmor | tee /usr/share/keyrings/rackslab.gpg > /dev/null

Create /etc/apt/sources.list.d/rackslab.sources with this content:

  • Debian 11 « bullseye »

  • Debian 12 « bookworm »

  • Debian unstable « sid »

  • Ubuntu 22.04 LTS « jammy »

Types: deb
URIs: https://pkgs.rackslab.io/deb
Suites: bullseye
Components: main
Architectures: amd64
Signed-By: /usr/share/keyrings/rackslab.gpg
Types: deb
URIs: https://pkgs.rackslab.io/deb
Suites: bookworm
Components: main
Architectures: amd64
Signed-By: /usr/share/keyrings/rackslab.gpg
Types: deb
URIs: https://pkgs.rackslab.io/deb
Suites: sid
Components: main
Architectures: amd64
Signed-By: /usr/share/keyrings/rackslab.gpg
Types: deb
URIs: https://pkgs.rackslab.io/deb
Suites: ubuntu22.04
Components: main
Architectures: amd64
Signed-By: /usr/share/keyrings/rackslab.gpg

Update packages sources metadata:

# apt update

Install Fatbuildr packages and dependencies:

# apt install fatbuildr

RPM (RHEL, CentOS, Rocky Linux, Fedora)

On RHEL8, CentOS 8, Rocky Linux 8 and AlmaLinux OS 8 some dependencies are missing in standard distribution repositories. You must enable EPEL el8 repositories to get all requirements on these distributions:

# dnf install -y epel-release

Download and save RPM repository kerying:

# curl https://pkgs.rackslab.io/keyring.asc --output /etc/pki/rpm-gpg/RPM-GPG-KEY-Rackslab

Create DNF repository file /etc/yum.repos.d/fatbuildr.repo:

  • RHEL8

  • Fedora 37

  • Fedora 38

These packages are also compatible with CentOS 8, Rocky Linux 8 and AlmaLinux OS 8. 
[rackslab]
name=Rackslab
baseurl=https://pkgs.rackslab.io/rpm/el8/main/$basearch/
gpgcheck=1
enabled=1
countme=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-Rackslab
[rackslab]
name=Rackslab
baseurl=https://pkgs.rackslab.io/rpm/fc37/main/$basearch/
gpgcheck=1
enabled=1
countme=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-Rackslab
[rackslab]
name=Rackslab
baseurl=https://pkgs.rackslab.io/rpm/fc38/main/$basearch/
gpgcheck=1
enabled=1
countme=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-Rackslab

Install Fatbuildr packages:

# dnf install fatbuildr

Instance

To setup Fatbuildr installation, you must define at least one instance with its build pipelines. For this quickstart, you can define the default instance by creating file /etc/fatbuildr/instances.d/default.yml with this basic content:

name: Corporation production instance
gpg:
  name: Infrastructure team
  email: infra@corp.tld
formats:
  deb:
  - name: bullseye
    env: bullseye
    tag: deb11
  - name: ubuntu22.04
    env: jammy
    tag: u2204
    mirror: http://archive.canonical.com/
    components: main restricted universe multiverse
  rpm:
  - name: el8
    env: rocky-8
    tag: el8
  - name: fc38
    env: fedora-38
    tag: fc38

In this generic example, you probably see some parameters you might want to adjust with your personal settings. Go ahead! The definitions of the instances and their build pipelines highly depend on their specific purposes. Please refer to instances pipelines definitions reference documentation for all details.

To grant users the permissions to use Fatbuildr, add them to fatbuildr system group:

# usermod -a -G fatbuildr $user

Where $user is the login of your user account (ex: john).

At this stage, you should be able to start using Fatbuildr with your user account. Try to list running tasks!

$ fatbuildrctl list
No running task

Keyring

The first step is to initialize the instance keyring with this command:

$ fatbuildrctl keyring create

This submits an asynchronous task, the random keys are securely generated on server side. After few seconds, you can get the information about the generated keyring:

$ fatbuildrctl keyring

Build environments

Then, container images must be created according to the instance build pipelines:

$ fatbuildrctl images --create

This command submits tasks to create one container image per artifact format declared in the instance build pipeline. For example, with the basic default instance definition provided above, it submit two tasks to create deb and rpm container images.

Then, build environment must be created in the container images by running this command:

$ fatbuildrctl images --create-envs

This submits tasks to create all build environments required for every distributions defined in the build pipelines. For example, with the default instance definition provided above, four tasks are submited to create build environment for bullseye, ubuntu22.04, el8 and fc36 distributions,

Fatbuildr is now ready to build artifacts!

Artifacts

You can build your first artifacts based on the examples provided with Fatbuildr installation:

$ fatbuildrctl build --artifact hello --distribution bullseye \
  --basedir /usr/share/doc/fatbuildr/examples \
  --name 'John Doe' --email john.doe@company.tld --message "First build!"

This submits a task to:

  • Download the source tarball of GNU Hello. The URL and the version of the tarball is defined in artifact definition artifact.yml file located in /usr/share/doc/fatbuildr/examples/hello directory.

  • And build Deb package of this software in Debian 10 « bullseye » build environment, using the packaging code available in /usr/share/doc/fatbuildr/examples/hello/deb directory.

After a successful build, packages are available in directory /var/lib/fatbuildr/registry/default.

To avoid repetitive command line parameters, you should definititely set your name and email address in your preferences file.

Then you can build your first RPM package:

$ fatbuildrctl build --artifact hello --distribution el8 \
  --basedir /usr/share/doc/fatbuildr/examples \
  --message "First RPM build!"

This submits a task to build RPM packages of the same GNU Hello software for RHEL8 distribution.

Fatbuildrweb

To explore and distribute built packages, you can launch Fatbuildrweb:

$ /usr/libexec/fatbuildrweb

With a web browser, connect to this URL: http://localhost:5000

In the web page, you should see the defined default instance. If you click on this instance, you can explore history of tasks outputs and all artifacts published in this instance registry.

Fatbuildrweb can also be used to deploy the packages. For example:

  • On Debian 10 « bullseye » :

    Install the instance the keyring:

    $ curl -sS http://localhost:5000/default/keyring.asc | gpg --dearmor | \
  sudo tee /usr/share/keyrings/fatbuildr-default.gpg > /dev/null

    Create APT source file /etc/apt/sources.list.d/fatbuildr-default.sources with this content:

    Types: deb
URIs: http://localhost:5000/default/deb
Suites: bullseye
Components: main
Architectures: amd64
Signed-By: /usr/share/keyrings/fatbuildr-default.gpg

    You can then install your hello package with these commands:

    $ sudo apt update && sudo apt install hello

  • On RHEL8:

    Install the instance keyring:

    $ curl -sS http://localhost:5000/default/keyring.asc | \
  sudo tee /etc/pki/rpm-gpg/RPM-GPG-KEY-Fatbuildr-default

    Create DNF repository file /etc/yum.repos.d/fatbuildr-default.repo with this content:

    [fatbuildr-default]
name=Fatbuildr default instance
baseurl=http://localhost:5000/default/rpm/el8/main/$basearch/
gpgcheck=1
enabled=1
countme=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-Fatbuildr-default

    You can then install your hello package with this command:

    $ sudo dnf install hello

Next steps

After this quickstart guide, you should get an overview of Fatbuildr purpose, features and capabilities.

The next steps are probably to: