readme

README.md

@@ -0,0 +1,113 @@
+# Setting up a LAVA instance
+
+This repository contains ansible scripts that help set up a LAVA instance on a Debian 9.4 (stretch) machine.
+
+## Installation
+```bash
+# Get the repository
+git clone http://git.k-space.ee/madislutter/ansible-lava.git
+cd ansible-lava
+
+# Put the IP address of your machine into the hosts file.
+vim hosts
+
+# Run the lava-install playbook. This will install the necessary packages 
+# from stretch-backports. Not using the stretch-backports would result in 
+# installing a deprecated version. It will also configure the apache 
+# server to serve the LAVA website.
+ansible-playbook lava-install.yml
+
+# Create a superuser account with the help of lava-create-user playbook
+ansible-playbook lava-create-user.yml
+```
+* The next commands need to be run in the target machine.
+* If your server doesn't have HTTPS then you need to add these two lines into /etc/lava-server/settings.conf.
+  ```
+  "CSRF_COOKIE_SECURE": false,
+  "SESSION_COOKIE_SECURE": false
+  ```
+  After editing the file, restart the django service for the changes to take effect.
+  ```bash
+  service lava-server-gunicorn restart
+  ```
+* Now log in through the web interface and create a token at http://\<ip-address>/api/tokens/.
+
+```bash
+lava-tool auth-add http://<username>@<ip-address>/
+# Paste the token you created
+
+# The next section will create a shortcut for lava-tool so that we
+# wouldn't have to type out the server address for each command.
+lava-tool auth-config --default-user http://<username>@<ip-address>/RPC2/
+lava-tool auth-config --endpoint-shortcut local http://<username>@<ip-address>/RPC2/
+```
+## Testing the setup, adding devices
+In order to test the setup, let's add a qemu device and a standard test job that should run if everything is set up correctly. The following commands should be run inside the target machine.
+```bash
+# Add the qemu device type
+lava-server manage device-types add qemu
+# Add the device itself. The last argument is the device name.
+lava-server manage devices add --device-type qemu --worker $(hostname -f) qemu01
+```
+* Test jobs can only be submitted to devices that have a device dictionary. So we need to add a device dictionary to the created device. Create a file with the following contents and name it qemu-dict.jinja2.
+```jinja2
+{% extends 'qemu.jinja2' %}
+{% set mac_addr = '52:54:00:12:34:59' %}
+{% set memory = '1024' %}
+```
+* Now add the device dictionary to the device.
+```bash
+lava-tool device-dictionary --update /qemu-dict.jinja2 local qemu01
+```
+* Navigate to this address http://\<ip-address>/scheduler/jobsubmit and submit [this standard test job](https://validation.linaro.org/static/docs/v2/examples/test-jobs/qemu-amd64-standard-stretch.yaml).
+
+If the job runs and succeeds then the setup is successful.
+
+
+## Debugging
+### supermin: failed to find a suitable kernel (host_cpu=x86_64)
+If the test job is not able to boot the device and the output contains this error then make sure you have a kernel installed in /boot directory.
+
+### Could not access KVM kernel module
+If the job is not able to boot the device and the output contains:
+```
+Could not access KVM kernel module: No such file or directory
+failed to initialize KVM: No such file or directory
+Connection closed
+```
+then make sure your kernel has the kvm module loaded:
+```bash
+lsmod | grep kvm
+```
+Sometimes the module is loaded, but the module files themselves aren't mounted in `/lib/modules/$(uname -r)`. This is especially likely if you are running inside a virtual machine. Run this to see if there is a problem with finding the module files:
+```bash
+modprobe kvm
+```
+A simple solution to bypass the kvm problem is to disable kvm in the test job definition. Just add `no_kvm: true` as seen in [this test job](https://git.k-space.ee/madislutter/lava-tests/src/master/jobs/inline-pwd.yaml).
+
+## Noteworthy
+
+### Creating a superuser account
+If you try to create a superuser account with this command:
+```bash
+lava-server manage users add --superuser
+```
+then be aware that users created like this don't actually get access to the Django admin area of the site at http://\<ip-address>/admin. A user gets access to that only if the account is created with these commands:
+```bash
+lava-server manage createsuperuser --username <username> --email <<e-mail>
+lava-server manage changepassword <username>
+```
+---
+### Use tmux for long-running processes
+Installing all the packages for the LAVA setup can take a long time. It's possible you'll get a broken pipe during the installation. For this reason it might make sense to SSH into the machine, start a tmux session there and install the necessary packages inside this session. If you get a broken pipe then you'll be able to reconnect to the machine and attach to the same tmux session.
+
+If you installed the packages outside a tmux session and there was a configuration prompt and you then got a broken pipe then you'll need to do this:
+```bash
+# Find the dpkg job and kill it
+ps aux | grep dpkg
+kill <pid>
+
+# Finish configuring the packages
+dpkg --configure -a
+```
+