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 12 « bookworm »
-
Debian 13 « trixie »
-
Debian unstable « sid »
-
Ubuntu 22.04 LTS « jammy »
-
Ubuntu 24.04 LTS « noble »
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: trixie
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
Types: deb
URIs: https://pkgs.rackslab.io/deb
Suites: ubuntu24.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:
|
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
-
RHEL9
-
Fedora 39
-
Fedora 40
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
These packages are also compatible with CentOS 9, Rocky Linux 9 and AlmaLinux OS 9. |
[rackslab]
name=Rackslab
baseurl=https://pkgs.rackslab.io/rpm/el9/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/fc39/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/fc40/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:
-
Initialize your own artifacts repository with your artifact definitions.
-
Explore
fatbuildrctl
command features. -
Define and customize instances build pipelines definitions.
-
Setup Fatbuildrweb to execute it permanently, and tune its settings.
-
Have fun!