How to deploy the CI

This CI is based on a Jenkins server capable of running a pipeline to fetch code, build it and test it on a real embedded board. It also provides a TFTP and an NFS server for booting the target machine from network.

The Jenkins, TFTP and NFS servers are all simultaneously set up using our docker-compose file.

Note: You may selectively disable one of the containers to run the corresponding server on the host machine. It is important to make sure a server is not running both on the docker container and the host machine at the same time.

Ansible is used to deploy and launch the tests on the target board and retrieve the result in the CI.

The folder cukinia contains template tests for validating the correct operation of the target board. You may find more information about this tool at https://github.com/savoirfairelinux/cukinia.

Environment requirements

Please make sure that docker and docker-compose packages are installed on the host machine.

The instructions to install Ansible on your machine are described at https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html

Create docker-compose environment file

A docker-compose environment file is used to configure all the environment-specific settings. This file can be generated by using the script generate_env.sh. It also generates and gives user permissions to the folders required by the CI, located inside /var/jenkins_home.

./generate_env.sh

Note: If you want to use a TFTP or an NFS server installed on your host machine, you need to specify their shared dir path with the --tftp-dir and --nfs-dir parameters:

./generate_env.sh --tftp-dir <tftp-on-host> --nfs-dir <nfs-on-host>

Deploying the Docker servers

Docker images can be built by using docker-compose. All docker-compose commands must be run at the directory level of the docker-compose.yaml file.

To build the Docker images for the three servers:

docker-compose build

Note: Docker images to be built can also be specified separately:

docker-compose build jenkins <other-docker-imgs>

Once the Docker images have been generated you can deploy and start them:

docker-compose up

Note: You can as well specify which servers to launch:

docker-compose up jenkins <other-docker-imgs>

You can later stop and restart the CI with docker-compose stop <imgs> and docker-compose start <imgs>.

For more informations about the docker-compose command see the official documentation at https://docs.docker.com/compose/.

Jenkins configuration

The Jenkins UI can be accessed from a navigator at localhost:8080. The initial password for the admin user can be found inside /var/jenkins_home/secrets/initialAdminPassword.

We recommend installing the following plugins for a user-friendly visualization of the pipeline and the tests run by cukinia: Pipeline: Stage View Plugin, JUnit and Blue Ocean.

Board configuration

The target board must be configured to:

• Boot from network: The bootloader must be configured to take the dtb and kernel from the TFTP server. The kernel must be configured to use the rootfs from the NFS.

• Ansible: An SSH server and Python3 must be installed in order to handle Ansible commands.

Test TFTP server

You can test the transfer of a file with the TFTP server with:

$ echo hello > <tftp-dir>/hello
$ tftp localhost
tftp> get hello
tftp> quit

Where is the shared directory by the server, /var/jenkins_home/tftp by default.

Test NFS server

You can test the NFS server by mounting its shared dir:

sudo mount -v -o vers=4,tcp localhost:/ /dir/to/mount