b59118 / fuego Goto Github PK

Fuego
=======================

Fuego is a test system designed specifically for embedded Linux testing.
It supports automated testing of embedded targets (boards or products)
from a host system.  This is it's primary method of test execution.

A quick introduction to Fuego is that is consists of a host/target script
engine, and ver 100 pre-packaged tests.  These are installed in a docker
container, along with a Jenkins web interface and job control system, ready
for out-of-the-box Continuous Integration testing of your embedded Linux
project.

To use Fuego, you need to install it, then add a board file to let
Fuego know information about the board you are testing. You also add
a toolchain (if needed) for your board, and then populate the Jenkins
interface with test jobs that you are interested in.

Then start testing!

Getting Started
---------------
The first thing to do with Fuego is to create your own Docker container
with the Fuego distribution of host-side packages (including Jenkins)
and tests.

Fuego currently comes in 2 source repositories: one for building the
container, and one with the tests.  This README is in the 'fuego' repository.
You also need the 'fuego-core' repository, in a directory parallel to this
one.

Installing Fuego to a docker container
-------------------------------------------------------------------------------
Run install.sh from the top directory. This launches the ``docker build''
command to create a docker image - named 'fuego' by default.
It also creates a container from this image, called 'fuego-container'

Note that if you have tests or test infrastructure that requires
access to USB or serial ports, you should run install.sh with the
'--priv' option, like so:
  ./install.sh --priv

Running
-------------------------------------------------------------------------------
To start your Fuego container, issue the following command top directory:

  ./start.sh fuego-container

(or, use the name of whatever container was created in the install stop).

The shell used to start the container will enter a shell inside the
container.  If you exit that shell, the container will stop, and you
will be returned to the host shell.

Once the container is started, a web interface to the test system will
be available at: http://localhost:8080/fuego


Configuration
-------------------------------------------------------------------------------
Please see the docs (docs/fuego-docs.pdf) for configuration and usage.

By default, Fuego configures Docker to use the host network.
(See the --net="host" option in fuego-host-scripts/docker-create-container.sh.)
Please see the Docker manual for different network setup options.

Updating fuego-core and fuego
-------------------------------------------------------------------------------
The repository fuego-core is mounted as a external docker volume. All you
need to do is to issue a ``git pull'' from the host directory. This will
update the following components:
- Fuego engine
- tests
- overlays

Board configurations and toolchain setup can be updated by doing ``git pull''
from within the fuego host directory.

Updating the Jenkins version
-------------------------------------------------------------------------------

Modify the version and checksum
    $ vi Dockerfile
        ARG JENKINS_VERSION=2.32.1
        ARG JENKINS_SHA=3cbe9b6d4d82c975642ea4409e21e087

Re-build the flot plugin
    $ sudo apt-get install maven
    $ vi pom.xml
        -> change the jenkins version
    $ mvn install
    $ cp target/flot.hpi

Re-build Jenkins' config.xml (if necessary):
    + Install fuego as usual with the new Jenkins version
    + Manual configuration (click on 'Manage jenkins')
        - configure system
            + environment variables
                FUEGO_CORE /fuego-core
                FUEGO_RW /fuego-rw
                FUEGO_RO /fuego-ro
        - Configure global security
            + plain text => safe html
    + Copy the new config.xml (/var/lib/jenkins/config.xml) to frontend-install

Rewrite Jobs config.xml (if necessary):
    + Configure the job manually and save it
    + Get the xml file
         java -jar /var/cache/jenkins/war/WEB-INF/jenkins-cli.jar -s http://localhost:8080/fuego get-job docker.default.Benchmark.Dhrystone
    + Modify ftc add-jobs (do_add_jobs()) as necessary

Initial test
------------
You can use the docker container as a fuego target in order to confirm that
the installation was successful.

# ftc add-nodes docker
# ftc add-jobs -b docker -p testplan_docker
# ftc add-jobs -b docker -t Benchmark.Dhrystone -s default

On the Jenkins interface, build the "docker.testplan_docker.batch" job.
It will trigger the rest of the jobs. To remove the jobs use:

# ftc rm-jobs docker.testplan_docker.*.*

License
-------------------------------------------------------------------------------
Fuego is licensed under the 3-clause BSD license. Please refer to LICENSE
for details. Jenkins is licensed under the MIT license.