...

Prerequisites

• A relatively modern Linux system.  This has been tried on Fedora 29 and Ubuntu 18.04, and Ubuntu 16.04 (However on 16.04 you need updated python packages, details below).  This has been shown to work in VM based install.
• root/sudo access on host system.  Root access is needed to add udev rules, install a few utilities, and run the udev-forward.py script.
• FRDM-K64F board

Setup Host System

Install Docker

...

Use the following link for instructions on how to install docker: https://docs.docker.com/install

On distributions like fedora & ubuntu its recommend to add your local user to the docker group as this will prevent you from having to use sudo to run the docker commands.  You can use the following command to add your user to the docker group:

sudo usermod -aG docker <USERNAME>

...

• https://docs.docker.com/config/daemon/systemd/#httphttps-proxy
• https://docs.docker.com/network/proxy/

...

Prerequisites

• A relatively modern Linux system.  This has been tried on Fedora 29 and Ubuntu 18.04, and Ubuntu 16.04 (However on 16.04 you need updated python packages, details below).  This has been shown to work in VM based install.
• root/sudo access on host system.  Root access is needed to add udev rules, install a few utilities, and run the udev-forward.py script.
• FRDM-K64F board

Setup Host System

1. Install Docker

   • Use the following link for instructions on how to install docker: https://docs.docker.com/

   compose/

   • install

   /
   

   Install python packages

   ( Note: These need to be installed such that they are able to run as root - either use systems packages or install in root user ( sudo pip3 install --user ):
   Major distributions have packages for pydev >= 0.18 and docker >= 2.0
   For Ubuntu 18.04: 

   • On distributions like fedora & ubuntu its recommend to add your local user to the docker group as this will prevent you from having to use sudo to run the docker commands.  You can use the following command to add your user to the docker group:

     Code Block
     language bash
     sudo

   apt-get install

   • usermod

   python3

   • -

   pyudev

   • aG

   python3-

   • docker

   For Ubuntu 16.04:

   Specific action is required because the distro package versions are too old.

   Code Block
   sudo pip3 install -U --user pyudev docker

   If this doesn't work, you need to rune the command in "sudo su -" shell.

   Code Block
   pip3 install -U --user pyudev docker

   NOTE: It might require to first export proxy settings in the shell.

   For Fedora:

   Code Block
   language bash
   sudo dnf install python3-pyudev python3-docker

   NOTE: Use only if you aren't able to find distro packages (or they're very old) for pyudev and docker python packages.

   Code Block
   language bash
   sudo pip3 install -U --user pyudev docker

   Install lavacli

   • <USERNAME>

     
     

   • Note: The instructions that follow assume you are in the docker group and don't need sudo to run docker.  If you don't add yourself you will need to explicitly add sudo  in front of the docker commands.
   • (OPTIONAL) Proxy Setup - If you are behind an http proxy, follow these instructions:
     • https://docs.docker.com/config/daemon/systemd/#httphttps-proxy
     • https://docs.docker.com/network/proxy/

2. Install Docker Compose

   Use the following link for instructions on how to install docker: https://docs.docker.com/compose/install/
   
   

3. Install python packages

   ( Note: These need to be installed such that they are able to run as root - either use systems packages or install in root user ( sudo pip3 install --user ):
   Major distributions have packages for pydev >= 0.18 and docker >= 2.0
   For Ubuntu 18.04: 

   Code Block
   language bash
   pip3sudo apt-get install python3--user lavacli

Determine Serial Number for board

Code Block
language bash
udevadm monitor -e | grep -i ID_SERIAL_SHORT

Plug in board, should see some output likeClone Git Repo

4. pyudev python3-docker

   
   

   For Ubuntu 16.04:

   
   

   
   

   
   

   
   

   
   

   
   

   
   

   Specific action is required because the distro package versions are too old.

   Code Block
   sudo pip3 install -U --user pyudev docker

   If this doesn't work, you need to rune the command in "sudo su -" shell.

   Code Block
   pip3 install -U --user pyudev docker

   NOTE: It might require to first export proxy settings in the shell.

   For Fedora:

   Code Block
   language bash

ID_SERIAL_SHORT=0240000031754e45001c0019948500046461000097969900
ID_SERIAL_SHORT=0240000031754e45001c0019948500046461000097969900
ID_SERIAL_SHORT=0240000031754e45001c0019948500046461000097969900
ID_SERIAL_SHORT=0240000031754e45001c0019948500046461000097969900

5. sudo dnf install python3-pyudev python3-docker

   NOTE: Use only if you aren't able to find distro packages (or they're very old) for pyudev and docker python packages.

   Code Block
   language bash

git

6. sudo pip3

clone

7. install -

b

8. U

lite https://git.lavasoftware.org/galak/docker-compose.git lava-docker-composeInstall usb-passthrough in /usr/local/bin 

9. --user pyudev docker

   
   

10. Install lavacli

    Code Block
    language bash

sudo

11. pip3

cp

12. install

lava

13. -

docker-compose/contrib/usb-passthrough /usr/local/bin

14. Modify  lava-docker-compose/contrib/LAVA.rules


    Replace  MYSERIALNUM with serial number from step 4.

    -user lavacli

    
    

# Example LAVA.rules for USB passthrough to container # # Assumes that usb-passthrough script is installed in # /usr/local/bin/passthrough # Pass all usb devices (TTY, block, CDC) to lava-dispatcher container # FRDM-K64F ACTION=="add", ENV{ID_SERIAL_SHORT}=="MYSERIALNUM", RUN+="/usr/local/bin/usb-passthrough -a -d %E{ID_SERIAL_SHORT} -i lava-dispatcher" # Pass TTY through to lava-ser2net container ACTION=="add", SUBSYSTEM=="tty

15. Determine Serial Number for board

    Code Block
    language bash

linenumberstrue

16. udevadm monitor -e | grep -i ID_SERIAL_SHORT

    Plug in board, should see some output like:

    Code Block
    language bash
    ID_SERIAL_SHORT=0240000031754e45001c0019948500046461000097969900 ID_SERIAL_SHORT=0240000031754e45001c0019948500046461000097969900 ID_SERIAL_SHORT=0240000031754e45001c0019948500046461000097969900 ID_SERIAL_SHORT=0240000031754e45001c0019948500046461000097969900

    
    

17. Clone Git Repo

    Code Block
    language bash
    git clone -b lite https://git.lavasoftware.org/galak/docker-compose.git lava-docker-compose

    
    

18. Install usb-passthrough in /usr/local/bin 

    Code Block
    language bash
    sudo cp lava-docker-compose/contrib/usb-passthrough /usr/local/bin

    
    

19. Modify  lava-docker-compose/contrib/LAVA.rules


    Replace  MYSERIALNUM with serial number from step 4.

    Code Block
    language bash linenumbers true
    # Example LAVA.rules for USB passthrough to container # # Assumes that usb-passthrough script is installed in # /usr/local/bin/passthrough # Pass all usb devices (TTY, block, CDC) to lava-dispatcher container # FRDM-K64F ACTION=="add", ENV{ID_SERIAL_SHORT}=="MYSERIALNUM", RUN+="/usr/local/bin/usb-passthrough -a -d %E{ID_SERIAL_SHORT} -i lava-ser2netdispatcher" #

    Change line #8 and #10 to look like:

    Pass TTY through to lava-ser2net container ACTION=="add", SUBSYSTEM=="tty", ENV{ID_SERIAL_SHORT}=="MYSERIALNUM", RUN+="/usr/local/bin/usb-passthrough -a -d %E{ID_SERIAL_SHORT} -i lava-ser2net"

    Change line #8 and #10 to look like:

    Code Block
    language bash linenumbers true
    # Example LAVA.rules for USB passthrough to container # # Assumes that usb-passthrough script is installed in # /usr/local/bin/passthrough # Pass all usb devices (TTY, block, CDC) to lava-dispatcher container # FRDM-K64F ACTION=="add", ENV{ID_SERIAL_SHORT}=="0240000031754e45001c0019948500046461000097969900", RUN+="/usr/local/bin/usb-passthrough -a -d %E{ID_SERIAL_SHORT} -i lava-dispatcher" # Pass TTY through to lava-ser2net container ACTION=="add", SUBSYSTEM=="tty", ENV{ID_SERIAL_SHORT}=="0240000031754e45001c0019948500046461000097969900", RUN+="/usr/local/bin/usb-passthrough -a -d %E{ID_SERIAL_SHORT} -i lava-ser2net"

    
    

20. install udev rule file

    Code Block
    language bash
    sudo cp lava-docker-compose/contrib/LAVA.rules /etc/udev/rules.d/

    
    

...

The following steps are related to getting docker to build and startup the containers for LAVA.  The docker-compose setup allows for us to coordinate multiple container instances together for the LAVA setup.  The docker-compose repository includes a  docker-compose.yaml  that describes the setup and configuration of the the LAVA containers.  The repository is based on the upstream LAVA project docker-compose repo.  The majority of changes are related to connecting microcontroller classes boards.  The two major changes are having a lava-dispatcher with additional software (flashing tools like pyOCD) and setting up a ser2net server to connect to the serial ports on the boards. 

NOTE: Disconnect board before doing these steps.

NOTE: sudo  is required on the docker-compose and make steps if your user isn't part of the docker group

NOTE: commands are relative to the lava-docker-compose directory from here forward.

Optional: Setup access for local IP/host

If you are running lava on a machine with a fixed IP (eg: a dedicated computer on your local network) you will want to modify the  overlays/lava-server/etc/lava-server/settings.conf file to allow access.  You'll want to modify the ALLOWED_HOSTS line to add the ip or hostname of the machine.  In the example below, the ip 192.168.1.14 was added, you'll want to keep 127.0.0.1 and localhost .

...

...

pyOCD) and setting up a ser2net server to connect to the serial ports on the boards. 

NOTE: Disconnect board before doing these steps.

NOTE: sudo  is required on the docker-compose and make steps if your user isn't part of the docker group

NOTE: commands are relative to the lava-docker-compose directory from here forward.

1. Optional: Setup access for local IP/host

   If you are running lava on a machine with a fixed IP (eg: a dedicated computer on your local network) you will want to modify the  overlays/lava-server/etc/lava-server/settings.conf file to allow access.  You'll want to modify the ALLOWED_HOSTS line to add the ip or hostname of the machine.  In the example below, the ip 192.168.1.14 was added, you'll want to keep 127.0.0.1 and localhost .

   Code Block
   language yml linenumbers true
   { "HTTPS_XML_RPC": false, "MOUNT_POINT": "/", "STATIC_URL": "/static/", "ALLOWED_HOSTS": ["192.168.1.14", "127.0.0.1", "localhost"], "CSRF_COOKIE_SECURE": false, "SESSION_COOKIE_SECURE": false, "EVENT_NOTIFICATION": true, "EVENT_TOPIC": "lava-server", "INTERNAL_EVENT_SOCKET": "tcp://lava-publisher:5557" }

   
   

2. Optional: Add the proxy settings in lite-lava-dispatcher and ser2net images

   It might be required to define proxy setting in lite-lava-dispatcher/Dockerfile and ser2net/Dockerfile

   Code Block
   language bash
   ENV http_proxy=http://<user>:<pwd>@<proxy>:<port> ENV https_proxy=http://<user>:<pwd>@<proxy>:<port>

   
   

3. Optional: Configure DNS in /etc/docker/daemon.json

   Get host DNS 

   Code Block
   language bash
   nmcli dev show | grep 'IP4.DNS

   Set reported value in /etc/docker/daemon.json

   Code Block
   language yml
   { "dns": ["w.x.y.z"] }

   
   

4. Run commands to build docker images and startup lava

   Code Block
   language bash
   docker-compose build make

   You'll see output of docker fetching and building the images, and then all LAVA containers starting up, followed by a fair amount of logging from LAVA itself as it starts up.  This may take a few minutes to complete.

   Here are some examples of the output one can expect during this phase:
   
   

   • Docker Compose/Build Phase

     Code Block
     language bash
     galak@ubuntu:~/lava-docker-compose$ make docker-compose up Creating volume "lava-server-pgdata" with default driver Creating volume "lava-server-devices" with default driver Creating volume "lava-server-health-checks" with default driver Creating volume "lava-server-joboutput" with default driver Pulling db (postgres:11.2-alpine)... 11.2-alpine: Pulling from library/postgres bdf0201b3a05: Pull complete 365f27dc05d7: Pull complete bf541d40dfbc: Pull complete 823ce70c3252: Extracting [========> ] 4.194MB/25.04MB a92a31ecd32a: Download complete 83cc8c6d8282: Download complete 7995b9edc9bf: Download complete 7616119153d9: Download complete b3f69561e369: Download complete

     
     

   • Lava containers being created

     Code Block
     language bash
     Creating lava-server-db ... done Creating lava-dispatcher ... done Creating lava-ser2net ... done Creating lava-publisher ... done Creating lava-master ... done Creating lava-logs ... done Creating lava-server ... done Creating apache2 ...

     
     

   • Lava starting up

     Code Block
     language bash
     lava-master | Applying lava_results_app.0012_namedtestattribute_metadata... OK lava-server | . lava-master | Applying lava_results_app.0013_buglinks... OK lava-master | Applying lava_results_app.0014_xaxis_maxlength_increase... OK lava-master | Applying dashboard_app.0002_auto_20140917_1935... OK lava-logs | . lava-master | Applying dashboard_app.0003_auto_20140926_1208... OK lava-master | Applying dashboard_app.0004_imagereportchart_is_delta... OK lava-dispatcher | 2019-05-09 19:01:08,522 DEBUG [BTSP] Checking master [lava-master:5556] to create socket for lava-dispatcher lava-dispatcher | 2019-05-09 19:01:08,524 DEBUG [BTSP] socket IPv4 address: 172.18.0.6 lava-dispatcher | 2019-05-09 19:01:08,525 INFO [BTSP] Greeting master => 'HELLO_RETRY' (using the same version?) lava-master | Applying dashboard_app.0005_imagereportchart_chart_height... OK lava-master | Applying dashboard_app.0006_auto_20141028_1146... OK lava-master | Applying dashboard_app.0007_imagereportchart_chart_visibility... OK lava-server | . lava-master | Applying dashboard_app.0008_imagechartfilter_is_all_tests_included... OK

     
     

   • Lava idle

     Code Block
     language bash
     lava-dispatcher | 2019-05-09 19:03:21,510 DEBUG PING => master (last message 20s ago) lava-master | 2019-05-09 19:03:21,513 DEBUG lava-dispatcher => PING(20) lava-dispatcher | 2019-05-09 19:03:21,519 DEBUG master => PONG(20) lava-master | 2019-05-09 19:03:36,201 INFO scheduling health checks: lava-master | 2019-05-09 19:03:36,205 INFO scheduling jobs: lava-master | 2019-05-09 19:03:38,651 DEBUG lava-logs => PING(20) lava-logs | 2019-05-09 19:03:38,648 DEBUG PING => master lava-logs | 2019-05-09 19:03:38,657 DEBUG master => PONG(20) lava-master | 2019-05-09 19:03:41,549 DEBUG lava-dispatcher => PING(20) lava-dispatcher | 2019-05-09 19:03:41,546 DEBUG PING => master (last message 20s ago) lava-dispatcher | 2019-05-09 19:03:41,555 DEBUG master => PONG(20) lava-master | 2019-05-09 19:03:56,221 INFO scheduling health checks: lava-master | 2019-05-09 19:03:56,225 INFO scheduling jobs: lava-logs | 2019-05-09 19:03:58,681 DEBUG PING => master lava-master | 2019-05-09 19:03:58,684 DEBUG lava-logs => PING(20) lava-logs | 2019-05-09 19:03:58,690 DEBUG master => PONG(20) lava-master | 2019-05-09 19:04:01,579 DEBUG lava-dispatcher => PING(20) lava-dispatcher | 2019-05-09 19:04:01,577 DEBUG PING => master (last message 20s ago) lava-dispatcher | 2019-05-09 19:04:01,584 DEBUG master => PONG(20)

     
     

5. Verify lava is running
   

   You can verify that lava has completed startup by trying to connect to the LAVA webserver in a web browser by going to localhost.

   Here's what the startup webpage should look like in your web browser:

   

...

You then need to bind your  host certificates to container by adding following line in lava-docker-compose/docker-compose.yaml:

  lava-master:
    container_name: lava-master
    image: ${DC_SERVER_IMAGE}
    volumes:
    ...
    - /usr/local/share/ca-certificates:/usr/local/share/ca-certificates:ro

Then, run the following command in the container and go back to job start step.

update-ca-certificates

...