Installing on a Debian system

These instructions cover installation on Debian. The supported versions are:

Distribution	Codename	Number	Support
Debian	experimental	n/a	No [1]
Debian	sid (unstable)	n/a	Yes [2]
Debian	trixie (testing)	n/a	Yes [3]
Debian	bookworm (stable)	12.*	Yes [4]
Debian	bullseye (oldstable)	11.*	No

Debian uses codenames for releases (bookworm, bullseye, buster) and names for suites (unstable, testing, stable & oldstable). When a new Debian major release is made, the packages in “testing” are frozen and become the new “stable”. A new codename is chosen for the new “testing” suite, and that will be the name for the next major release in the cycle.

To allow the table to refer to the same package versions consistently over time, codenames are used here. When a Debian release is made, a new codename is applied to the testing suite and LAVA releases after that point will include that codename in the table.

Note

LAVA used to be supported on Ubuntu directly, but is not any more due to lack of resources to maintain and test that support. Support may be re-instated if more effort becomes available in the future. The last version of LAVA supported in Ubuntu was 2015.9.post1.

[1]

experimental allows updates to be selected on top of unstable (or the current testing) during times when testing is frozen ahead of a release of Debian stable. Experimental will typically have no LAVA packages outside of a Debian release freeze.

[2]

sid is the name of the unstable suite which never gets released but acts as a feed for testing. As the name suggests, unstable can be broken without warning and installation of complex packages like LAVA can often fail. Unstable is never recommended for production instances of any software, including LAVA.

[3]

trixie is the name of the next Debian release after bookworm, which is supported automatically via uploads to sid (unstable). Trixie is not recommended for production instances of LAVA.

When trixie is released as Debian 13, it will use the suite name stable, testing will get the codename of the next Debian stable release, and bookworm will become oldstable.

[4]

bookworm is the name of the stable version of Debian. LAVA is fully supported on this Debian version. It’s recommended to use bookworm for production instances.

You can track the versions of LAVA packages in the various Debian suites by following links from the Debian package tracker for lava.

Recommended Debian architectures

LAVA is intended to provide a CI system which is capable of handling dozens or hundreds of simultaneous test jobs across dozens of devices.

Whilst it is possible to install and operate LAVA on 32 bit architectures like i386 and armhf, this is not recommended for any production instance. The memory requirements for the master will increase with the number of users and if your instance is publicly visible on the internet, limited access to RAM is known to cause problems. The memory, CPU and I/O requirements of lava-dispatcher depend on the number and type of devices as well as the number of test jobs which can run simultaneously. For example, experience has shown that any test job using fastboot requires a single CPU core (not hyperthread) per attached device, as well as at least one core for the base OS. armhf in particular can struggle to provide enough processing power (CPU or I/O or RAM) for such devices. Each QEMU device can require more RAM than would be available on most 32 bit systems.

LAVA is routinely used on amd64 and arm64 architectures. Packages for other 64 bit architectures like ppc64, ppc64el and s390x are available from Debian.

Each lab will be different and there are no definitive guidelines on what hardware specifications to choose. Start slowly and grow your lab one step at a time. If in doubt, talk to us.

See also

How many devices is too many for one worker?

LAVA repositories

As well as being uploaded to Debian, Production releases of LAVA are also uploaded to the LAVA Software Community Project repository at https://apt.lavasoftware.org/ . This uses the LAVA Archive signing keys - a copy of the key is available in the repository and on key servers.

It is recommended to use this repository as it contains more up to date releases.

See also

Dependency Requirements.

Releases

deb https://apt.lavasoftware.org/release bookworm main

Note

The LAVA repositories only provide packages for amd64 and arm64. See Recommended Debian architectures.

In times when the current production release has not made it into either stable or testing (e.g. due to a migration issue or a pre-release package freeze in Debian), this repository should be used instead.

Daily builds

Interim builds (including release candidates) are available from the daily builds repository, using the same suites:

deb https://apt.lavasoftware.org/daily bookworm main

Snapshots

When a build is updated in the repositories, a copy of the same build is created in the snapshot folder:

https://apt.lavasoftware.org/snapshot/

Entries are created according to the suite for which it was built and the year, month and day of the build.

Bookworm users

Note

The recommended base for LAVA is Debian bookworm

deb https://apt.lavasoftware.org/release bookworm main

LAVA Archive signing keys

The LAVA Software Community Project uses two keys for the repositories.

The daily builds are signed using:

pub  2048R/C77102A9 2014-06-06 LAVA build daemon (Staging) <lava-lab@linaro.org>
     Key fingerprint = 45AD 50DC 41AE D421 FF5B  33D4 ECF3 C05C C771 02A9
uid                  LAVA build daemon (Staging) <lava-lab@linaro.org>

Production releases are signed using:

pub   rsa4096/A791358F2E49B100 2018-10-02 [SC]
     Key fingerprint = C87D 63FD 9355 35CF B0CA  F5C2 A791 358F 2E49 B100
uid                 [ultimate] LAVA Software release key <release@lavasoftware.org>
sub   rsa4096/42124FB9C30943EC 2018-10-02 [E]

Both keys can be downloaded and added to keyrings easily:

$ sudo apt install curl gpg     # just in case you don't have them installed yet
$ curl -fsSL "https://apt.lavasoftware.org/lavasoftware.key.asc" | gpg --dearmor > lavasoftware.gpg
$ sudo mv lavasoftware.gpg /usr/share/keyrings
$ sudo chmod u=rw,g=r,o=r /usr/share/keyrings/lavasoftware.gpg

Now add the repository:

$ echo 'deb [signed-by=/usr/share/keyrings/lavasoftware.gpg] https://apt.lavasoftware.org/release bookworm main' | sudo tee /etc/apt/sources.list.d/lavasoftware.list

After that step, run apt update again to locate the required dependencies:

$ sudo apt update

Production releases

See also

Setting up a LAVA instance.

LAVA is currently packaged for Debian using Django 3.2 and PostgreSQL. LAVA packages are now available from official Debian mirrors for Debian unstable. e.g. to install the master, use:

$ sudo apt install postgresql
$ sudo apt install lava-server

If the default Apache configuration from LAVA is suitable, you can enable it immediately:

$ sudo a2dissite 000-default
$ sudo a2enmod proxy
$ sudo a2enmod proxy_http
$ sudo a2ensite lava-server.conf
$ sudo systemctl restart apache2.service

Edits to the /etc/apache2/sites-available/lava-server.conf file will not be overwritten by package upgrades unless the admin explicitly asks dpkg to do so.

If you later choose to remove lava-server, the apache modules enabled above can be disabled using:

$ sudo a2dismod proxy
$ sudo a2dismod proxy_http

Configuring the installation

If the installation uses http://localhost, the remaining configuration is to disable some of the Django security checks which expect https.

See also

Check LAVA instance and Using localhost or non HTTPS instance URL

If the installation uses a remote slave, then HTTPS should be used.

Using a domain name other than localhost

While having LAVA run on localhost is a great point to start for doing the first steps, a real deploy of LAVA will most probably end up on a domain e.g. like lava.example.net. There are some more configuration to do to achieve this:

Set up Apache configuration to serve LAVA on your desired domain by editing Apache configuration and/or /etc/apache2/sites-available/lava-server.conf to fit to your needs. Reload apache configuration by systemctl reload apache2

Append this line to /etc/lava-server/lava-server-gunicorn:

ALLOWED_HOSTS='lava.example.net'

restart lava-server-gunicorn service for the changes to get applied:

$ systemctl restart lava-server-gunicorn.service

Remember to also modify /etc/lava-dispatcher/lava-worker and add domain name there too (and edit worker configuration in django). Don’t forget to restart worker afterwards for the changes to get applied:

$ systemctl restart lava-worker.service

Setting up a reverse proxy

In order to use lava-server behind a reverse proxy, configure lava-server as usual and then setup a reverse proxy. The following simple Apache configuration snippet will work for most setups:

ProxyPass / http://lava_server_dns:port/
ProxyPassReverse / http://lava_server_dns:port/
ProxyPreserveHost On
RequestHeader set X-Forwarded-Proto "https" env=HTTPS

Remember to also include ALLOWED_HOSTS as written above.

This configuration will work when proxifying:

http://example.com/ => http://lava.example.com/

If you want the application to answer on a specific base URL, configure lava-server to answer on this base URL and then configure the reverse proxy to proxify the same base URL. For instance you can have:

http://example.com/lava => http://lava.example.com/lava

In order to serve LAVA under /lava you should update the settings and add:

"STATIC_URL": "/lava/static/",
"MOUNT_POINT": "/lava",
"LOGIN_URL": "/lava/accounts/login/",
"LOGIN_REDIRECT_URL": "/lava/",

Having two different base URLs is more awkward to setup. In this case you will have to also setup Apache modules like Substitute to alter the HTML content on the fly. This is not a recommended setup.

Depending on your setup, you should also have a look at ProxyPassReverseCookieDomain and ProxyPassReverseCookiePath to set the cookie domain and path correctly.

Superuser

See also

Adding users and groups

LDAP

In LAVA instances that use LDAP for external authentication, log in once with the user account that will be granted superuser privileges in the LAVA web UI. Then use the following command to make this user a superuser:

$ sudo lava-server manage authorize_superuser --username {username}

Note

{username} is the username of LDAP user.

Alternatively, the addldapuser command can be used to populate a user from LDAP and also grant superuser privilege as follows:

$ sudo lava-server manage addldapuser --username {username} --superuser

Note

{username} is the username of LDAP user.

See also

Adding users and groups

Local Django Accounts

After initial package installation, you might wish to create a local superuser account:

$ sudo lava-server manage createsuperuser --username $USERNAME --email=$EMAIL

If you do not specify the username and email address here, this command will prompt for them.

An existing local Django superuser account can also be converted to an LDAP user account without losing data, using the mergeldapuser command, provided the LDAP username does not already exist in the LAVA instance:

$ sudo lava-server manage mergeldapuser --lava-user <lava_user> --ldap-user <ldap_user>

Debugging the Installation

After your LAVA instance is successfully installed, if you face any problem consult Administrator debugging

Using localhost or non HTTPS instance URL

Newer versions of django include improved security features which can affect how LAVA is used as http://localhost. By default, django enforces behavior to ensure safe use of https:// which can prevent attempts to sign in to a LAVA instance using http://localhost/.

To enable localhost, you may need to disable at least these security defaults by adding the following options to LAVA settings file:

"CSRF_COOKIE_SECURE": false,
"SESSION_COOKIE_SECURE": false

Note

This is the reason, if you see issues regarding CSRF token while trying to login with an username. The common error message reported is CSRF verification failed. Request aborted.

The LAVA settings are stored in yaml in:

• /etc/lava-server/settings.conf

• /etc/lava-server/settings.yaml

• /etc/lava-server/settings.d/*.yaml

LAVA will load the files in this exact order.Files in the settings.d directory will be alphabetically ordered.

If a variable is defined in two files, the value from the last file will override the value from first one. Any changes made in LAVA settings yaml file will require a restart of lava-server-gunicorn service for the changes to get applied:

$ systemctl restart lava-server-gunicorn.service

Note

From 2020.05 release the settings files will not be created by default on fresh installations. The settings file can be added in settings.d directory or settings.conf should be created.

See also

Check LAVA instance