If you are interested in a quick outline of steps, please see the Fuego Quickstart Guide instead.
- 1. install pre-requisite software
- 2. download the Fuego repository
- 3. build your Fuego container
- 4. start the container
- 5. access the Jenkins interface
On Ubuntu, try the following commands:
These commands may be different for other distributions of Linux (such as Fedora, RedHat, CentOS, Mint, etc.)
These steps and commands will be described in the sections that follow.
The reason there are two repositories is that the different repositories hold different pieces of the system, and this allows for them to be upgraded independently of each other.
The repositories are currently hosted on bitbucket.org, under the the 'fuegotest' account.
After downloading the repositories, switch to the 'fuego' directory, as shown in the example.
Note that these git commands will download the 'master' branch of the repository, which is the current main released version of Fuego.
NOTE: If you are experimenting with an unreleased version of Fuego in the 'next' branch, then please replace the 'git clone' command in the instructions above with these:
This uses '-b next' to indicate a different branch to check out during the clone operation.
install.sh uses docker and the Dockerfile in the fuego directory to create a docker container with the Fuego Linux distribution.
This operation may take a long time. It takes about 45 minutes on my machine. This is due to building a nearly complete distribution of Linux, from binary packages obtained from the Internet.
This step requires Internet access. You need to make sure that you have proxy access to the Internet if you are behind a corporate firewall.
Please see the section "Alternative Installation Configuratons" below for
other arguments to
install.sh, or for alternative installation scripts.
For example, the Fuego distribution includes
- the 'Jenkins' continuous integration server
- the 'netperf' server, for testing network performance.
- the 'ttc' command, which is a tool for board farm management
- the python 'jenkins' module, for interacting with Fuego's Jenkins instance
- and many other tools, programs and modules used by Fuego and its tests
Fuego commands execute inside the Fuego docker container, and Fuego operations initiate in the container, but may access hardware (such as USB ports, networking, or serial ports) that are outside the container.
To do that, you can create a 'privileged' Fuego container, using the '--priv' options with install.sh:
When --priv is used, Fuego uses
docker-create-usb-privileged-container.sh can be edited, before
running install.sh, to change the set of hardware devices
that the docker container will have privileged access to.
This is done by adding more bind mount options to the 'docker create' command inside this script. Explaining exactly how to do this is outside the scope of this documentation. Please see documentation and online resources for the 'docker' system for information about this.
The script currently creates bind mounts for:
- /dev/bus/usb - USB ports, and newly created ports
- /dev/ttyACM0 - serial port 0
- /dev/ttyACM1 - serial port 1
- /dev/serial - general serial ports, and newly created ports
If you experience problems with Fuego accessing hardware on your host system, you may need to build the Fuego docker container using additional bind mounts that are specific to your configuration. Do so by editing docker-create-used-privileged-container.sh, removing the old container, and re-running './install.sh --priv' to build a new container with the desired privileges.
You can provide a different name for the Fuego image and container, by supplying one on the command line for install.sh, like so:
This would create a docker image named 'my-fuego' and a docker container named 'my-fuego-container'
When you run the 'start.sh', the terminal where the script is run will be placed at a shell prompt inside the docker container. The session will be logged in as the root user inside the container. The container will run until you exit this top-level shell. Therefore, you should leave it (the shell and the terminal that your ran 'start.sh' from) running for the duration of your testing.
Here is an example showing use of firefox to access the Jenkins interface with Fuego $ firefox http://localhost:8090/fuego }}}
To access the Fuego interface you can use any browser - not just Firefox.
In your browser, you should see a screen similar to the following:
Note that this web interface is available from any machine that has access to your host machine via the network. This means that test operations and test results are available to anyone with access to your machine. You can configure Jenkins with different security to avoid this.
Some 'ftc' commands can be run outside the container, but other require that you execute the command inside the container.
To start another shell prompt inside the currently running Fuego docker
container, you can use the script 'fuegosh'. This helper script is
You may find it convenient to copy this script to
a 'bin' directory on your system (either /usr/local/bin or ~/bin) that
is already in your PATH.
If you run 'fuegosh', it will place you at a shell prompt inside the Fuego docker container, like so:
- add one or more hardware boards (board definition files)
- add a toolchain
- populate the Jenkins interface with test jobs
These steps are described in subsequent sections of this documentation.
The configuration alternatives that are supported are:
- install using a different TCP/IP port for Jenkins
- install without the Jenkins server
- install directly to your host (not inside a container)
To use a different port than 8090 for Jenkins, specify it after the image name on the command line when you run install.sh. Note that this means that you must specify a Docker image name in order to specify a non-default port. For example:
This would install Fuego, with an docker image name of 'fuego', a docker container name of 'fuego-container', and with Jenkins configured to run on port 7777
install.shsupports the option '--nojenkins' which produces a docker container without the Jenkins server. This reduces the overhead of the docker container by quite a bit, for those users.
Inside the docker container, the Fuego core is still available. Boards, toolchains, and tests are configured normally, but the 'ftc' command line tool is used to execute tests. There is no need to use any of the 'ftc' functions to manage nodes, jobs or views in the Jenkins system. 'ftc' is used to directly execute tests using 'ftc run-test', and results can be queried using 'ftc list-runs' and 'ftc gen-report'.
When using Fuego with a different results visualization backend, the user will use 'ftc put-run' to send the test result data to the configured back end.
A separate install script, called 'install-debian.sh' can be used in place of 'install.sh' to install the Fuego system onto a Debian-based Linux distribution.
Please note that installing without a container is not advised unless you know exactly what you are doing. In this configuration, Fuego will not be able to manage host-side test dependencies for you correctly.
Please note also that executing without a container presents a possible security risk for your host. Fuego tests can run arbitrary bash instruction sequences as part of their execution. So there is a danger when running tests from unknown third parties that they will execute something on your test host that breaches the security, or that inadvertently damages you filesystem or data.
However, despite these drawbacks, there are test scenarios (such as installing Fuego directly to a target board), where this configuration makes sense.