Installation

The local-builder is available either as a lxc / incus container, or as a OCI / Docker container. According to your choice, please follow one of the two paragraphs below.

However, do not forget to follow the third paragraph in order to set-up your host for cross-compilation.

The last paragraph is about the setup of a HTTP/HTTPS proxy configuration. Follow it only if you are using a proxy!

Using Docker

Install Docker on your computer

If it is not already done, install docker on your computer using the method that fit your distribution (cf. the official website).

We recommend using the official Docker repository in order to have the latest version of Docker.

We also recommend to add your user to the docker group (cf. command below). Like this, you won’t have to run every docker command with sudo. In the rest of this documentation, we consider that your user is added to the docker group, therefore, we use the docker command without sudo.

# Add your user to the 'docker' group
sudo usermod -aG docker ${USER}

NOTE:
If your organization uses a proxy server to connect to the internet, you may also need to configure Docker daemon to use the proxy server.
Please refer to this documentation available on docs.docker.com

Create the mount points on your host

Firstly, we need to create some directories on your computer, depending if you already have installed rp-cli, these directories may already exist.

mkdir -p $HOME/my_rp_builder_dir/gitsources
mkdir -p $HOME/my_rp_builder_dir/gitpkgs

Start the docker local-builder

Iot.bzh has its own public docker registry, use it to deploy your local-builder. Choose the right command according to your distribution.

  • For Debian/Ubuntu:
docker run --detach \
      --init \
      --cap-add=SYS_ADMIN \
      --security-opt apparmor:unconfined \
      --user $(id -u):$(id -g) \
      --publish 8080:8080 \
      --volume ~/my_rp_builder_dir:/home/devel/rp-build:z \
      --name redpesk-localbuilder \
      registry.redpesk.bzh/redpesk-ci/redpesk-localbuilder:latest
  • For Almalinux/Fedora:
docker run --detach \
      --init \
      --cap-add=SYS_ADMIN \
      --security-opt label:disable \
      --user $(id -u):$(id -g) \
      --publish 8080:8080 \
      --volume ~/my_rp_builder_dir:/home/devel/rp-build:z \
      --name redpesk-localbuilder \
      registry.redpesk.bzh/redpesk-ci/redpesk-localbuilder:latest

From now, you can manage your container using the redpesk-localbuilder name. For example:

docker container stop redpesk-localbuilder
docker container start redpesk-localbuilder

Using Incus (LXC)

Install Incus on your computer

In order to be able to run the local-builder as a LXC container, you will need incus (this is a recent fork of lxd that has been restricted recently by Canonical).

Please install incus, by following their How to install Incus.

We advice to install at least the version 6.5 of incus. If your native incus package is older than that, please use the Zably package repository.

At the end of the installation, initialize incus on your machine using the minimal configuration.

incus admin init --minimal

Download locally the localbuilder image

First, download locally the latest localbuilder image available and its md5 checksum file.

wget https://download.redpesk.bzh/redpesk-ci/redpesk-builder/lxc/redpesk-localbuilder_latest.tar.gz
wget https://download.redpesk.bzh/redpesk-ci/redpesk-builder/lxc/redpesk-localbuilder_latest.md5

Then, check that the downloaded image is valid.

md5sum --check redpesk-localbuilder_latest.md5

Finally, import the image inside incus

incus image import ./redpesk-localbuilder_latest.tar.gz --alias redpesk-localbuilder-image

Configure and start the localbuilder

Firstly, we need to create some directories on your computer, depending if you already have installed rp-cli, these directories may already exist.

mkdir -p $HOME/my_rp_builder_dir/gitsources
mkdir -p $HOME/my_rp_builder_dir/gitpkgs

Then, we still have to run several command lines to finish to configure the localbuilder.

# Create the redpesk-localbuilder using the previously imported image
incus launch redpesk-localbuilder-image redpesk-localbuilder --config security.privileged=true --config security.nesting=true

# Add the loop-control device
incus config device add redpesk-localbuilder loop-control unix-char path=/dev/loop-control

# Import your ssh key
incus config device add redpesk-localbuilder my_ssh disk source=~/.ssh path=/home/devel/.ssh

# Mapping host directories in the container
incus config device add redpesk-localbuilder my_rp_build disk source=$HOME/my_rp_builder_dir path=/home/devel/rp-build

Finally, restart your localbuilder.

incus restart redpesk-localbuilder

Configure your host for cross-compilation

Most of the time, this is really straight forward. Firstly, install the qemu-user-static package. Just use your main package manager.

  • For Debian/Ubuntu:
sudo apt-get install qemu-user-static
  • For Almalinux/Fedora:
sudo dnf install qemu-user-static

Verify that you have the ‘F’ flag in the /proc/sys/fs/binfmt_misc/qemu-aarch64 file:

enabled
interpreter /usr/bin/qemu-aarch64-static
flags: F
offset 0
magic 7f454c460201010000000000000000000200b700
mask ffffffffffffff00fffffffffffffffffeffffff

NOTE:
You can have more than one flag in this file, and the interpreter can be another binary (especially in recent Debian/Ubuntu system), most of the time this does not affect the local-builder proper functioning.

Setup a HTTP/HTTPS proxy configuration

It is possible to declare a proxy (like Zscaler) in the local-builder.

There are pre-declared variables in the local-builder environment:

  • HTTP_PROXY: route HTTP traffic through a specified proxy
  • HTTPS_PROXY: route HTTPS traffic through a specified proxy for a secure web traffic
  • NO_PROXY: allow domains or IP addresses to bypass the proxy

You simply must do both things to use the local-builder within the proxy:

  • these above variables in the user host which calls rp-cli program
  • configure these variables inside the localbuilder through a rp-cli call

Proxy configuration example in the host and in the local-builder

Save your container IP address in a variable which will be used below commands.

  • Using Incus (LXC) container 
    container_name="redpesk-localbuilder"     # adapt name if needed
export CONTAINER_IP_ADDRESS=$(incus ls $container_name --format json |jq -r '.[0].state.network.eth0.addresses[0].address')
  • Using Docker (OCI) container 
    container_name="redpesk-localbuilder"     # adapt name if needed
export CONTAINER_IP_ADDRESS=$(docker inspect -f json $container_name |jq -r '.[].NetworkSettings.IPAddress')

    NOTE:
    Don’t forget to configure Docker daemon to also use the proxy server.
    Please refer to this documentation available on docs.docker.com

Proxy URL setup

Depending on your needs, you simply need to set these variables like below:

# HTTP_PROXY
export http_proxy="http://your_proxy_address:port"
export no_proxy="localhost,$CONTAINER_IP_ADDRESS"
rp-cli local exec "/usr/bin/setup_proxy -hp \"$http_proxy\""

# HTTPS_PROXY
export https_proxy="https://your_proxy_address:port"
export no_proxy="localhost,$CONTAINER_IP_ADDRESS"
rp-cli local exec "/usr/bin/setup_proxy -hsp \"$https_proxy\""

# NO_PROXY
export no_proxy="domain.com,localhost,127.0.0.1,$CONTAINER_IP_ADDRESS"
rp-cli local exec "/usr/bin/setup_proxy -n localhost,127.0.0.1"

Proxy SSL certificat (OPTIONAL)

Depending on your setup, you may also need to provide the ssl certificat of your proxy.

To do so, just copy your certificat file into the localbuilder container and refresh/consolidate CA certificats definition:

  • Using Incus (LXC) container 
    container_name="redpesk-localbuilder"     # adapt name if needed
incus file push ./MY_PROXY_SERVER_CERTIFICAT.crt ${container_name}:/etc/pki/ca-trust/source/anchors/
incus exec ${container_name} update-ca-trust
  • Using Docker (OCI) container 
    container_name="redpesk-localbuilder"     # adapt name if needed
docker cp ./MY_PROXY_SERVER_CERTIFICAT.crt ${container_name}:/etc/pki/ca-trust/source/anchors
docker exec --user root ${container_name} update-ca-trust