Installing Fuego
If you are interested in a quick outline of steps, please see the Fuego Quickstart Guide instead.
Overview [edit section]
The overview of the steps is:- 1. install pre-requisite software
- 2. download the Fuego repositories
- 3. build your Fuego container
- 4. start the container
- 5. access the Jenkins interface
Install pre-requisite software [edit section]
To retrieve the fuego software and create the docker image for it, you need to have git and docker installed on your system.On Ubuntu, try the following commands:
$ sudo apt-get install git $ sudo apt-get install docker.io
These commands may be different for other distributions of Linux (such as Fedora, RedHat, CentOS, Mint, etc.)
Overview of remaining steps [edit section]
Steps 2 through 5 of the installation can be performed with the following Linux commands:
$ git clone https://bitbucket.org/tbird20d/fuego.git $ git clone https://bitbucket.org/tbird20d/fuego-core.git $ cd fuego $ ./install.sh $ ./start.sh $ firefox http://localhost:8080/fuego
These steps and commands will be described in the sections that follow.
Install the Fuego repositories [edit section]
The Fuego system is available in 2 git repositories, which should be installed next to each other in the same directory. One repository is called 'fuego' and the other is 'fuego-core'.The reason there are two repositories is that the different repositories hold different pieces of the system, and so that they can be upgraded independently of each other.
The repositories are currently hosted on bitbucket.org, under the personal account of Tim Bird (the current primary maintainer of Fuego).
Fuego repository [edit section]
The 'fuego' repository has the code and files used to build the Fuego docker container. It also has the fuego-ro directory, which has board definition files, various configuration files, miscellaneous scripts, and other items which are used by Fuego for container management or other purposes.
Fuego-core repository [edit section]
The 'fuego-core' repository has the code which implements the core of the Fuego test execution engine, as well as the pre-packaged tests included with the system. This includes the overlay generator, the results parser, the Fuego shell function library, the directory of tests, and the main fuego command line tool 'ftc'.
Downloading the repository [edit section]
You can use 'git clone' to download the repositories, like so:$ git clone https://bitbucket.org/tbird20d/fuego.git $ git clone https://bitbucket.org/tbird20d/fuego-core.git $ cd fuego
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.
Downloading a different branch [edit section]
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:
$ git clone -b next https://bitbucket.org/tbird20d/fuego.git $ git clone -b next https://bitbucket.org/tbird20d/fuego-core.git $ cd fuego
This uses '-b next' to indicate a different branch to check out during the clone operation.
Create the Fuego container [edit section]
The third step of the installation is to run install.sh to create the Fuego docker container. First, change to the 'fuego' directory, and run the script from the current directory, like so:
$ cd fuego ; ./install.sh
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.
Fuego Linux distribution [edit section]
The Fuego Linux distribution is a distribution of Linux based on Debian Linux, with many additional packages and tools installed. These additional packages and tools are required for aspects of Fuego operation, and to support host-side processes and services needed by the tests included with Fuego.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.
Configuring for 'privileged' hardware access [edit section]
In many configurations, Fuego can perform its operations using only network operations. However, depending on the configuration of your boards, or your lab hardware, and the relationship between your host and target computers used for testing, you may need to access other hardware on your host machine.To do that, you can create a 'privileged' Fuego container, using the '--priv' options with install.sh:
$ cd fuego ; ./install.sh --priv
Customizing the privileged container [edit section]
Note that using '--priv' causes install.sh to use a different container creation script. Normally (in the non --priv case), install.sh usesfuego-host-scripts/docker-create-container.sh.
When --priv is used, Fuego uses fuego-host-scripts/docker-create-usb-privileged-container.sh.
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 volume 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 volume 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 volume 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.
Using an different container name [edit section]
By default, install.sh creates a docker image called 'fuego' and a docker container called 'fuego-container'. There are some situations where it is desirable to use different names. For example, having different container names is useful for Fuego self-testing. It can also used to do A/B testing when migrating from one release of Fuego to the next.You can provide a different name for the Fuego image and container, by supplying one on the command line for install.sh, like so:
$ cd fuego ; ./install.sh my-fuego
This would create a docker image named 'my-fuego' and a docker container named 'my-fuego-container'
Start the Fuego container [edit section]
To start the Fuego docker container, use the 'start.sh' script.
$ ./start.sh
Using a different container name [edit section]
By default, start.sh will start the container named 'fuego-container' (which is the default Fuego docker container name). However, if you created a different container name, you can specify the name on the command line, like so:
$ ./start.sh 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.
Access the Fuego Jenkins web interface [edit section]
Fuego includes a version of Jenkins and a set of plugins as part of its system. Jenkins is running inside the Fuego docker container. By default the Fuego Jenkins interface runs on port 8080, with an URL path "/fuego".Here is an example showing use of firefox to access the Jenkins interface with Fuego $ firefox http://localhost:8080/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.
Access the Fuego docker command line [edit section]
For some Fuego operations, it is handy to use the command line (shell prompt) inside the docker container. In particular, parts of the remaining setup of your Fuego system involve running the 'ftc' command line tool.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
located at: fuego/fuego-ro/scripts/fuegosh.
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:
$ fuegosh root@hostname:/#
Remaining steps [edit section]
Fuego is now installed and ready for test operations. However, some steps remain in order to use it with your hardware. You need to:- 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.
See: