Skip to content

Latest commit

 

History

History
220 lines (173 loc) · 7.93 KB

Installing.asciidoc

File metadata and controls

220 lines (173 loc) · 7.93 KB

openQA installation guide

Table of Contents

Introduction

openQA is an automated test tool that makes it possible to test the whole installation process of an operating system. It’s free software released under the GPLv2 license. The source code and documentation are hosted in the os-autoinst organization on GitHub.

This document provides the information needed to install and setup the tool, as well as information useful for everyday administration of the system. It’s assumed that the reader is already familiar with openQA and has already read the Starter Guide, available at the official repository.

Installation

The easiest way to install openQA is from packages. You can find them in OBS in the openQA repository or the latest development version can also be found in OBS in the openQA:devel repository. Installation on openSUSE is therefore pretty simple:

zypper ar -f obs://devel:openQA/openSUSE_13.1 openQA
zypper ar -f obs://devel:openQA:devel/openSUSE_13.1 openQA-devel
zypper ar -f obs://devel:openQA:devel:13.1/openSUSE_13.1 openQA-devel-perl-modules
zypper in openQA
# Init database
/usr/share/openqa/script/initdb --init_database
# Start WebUI
systemctl start openqa-webui

Now you have the WebUI running. You can take a look at the WebUI at http://localhost:9526 but so far it is empty. You need to do a few more actions to get it configured in a way that it will be able to run tests.

Basic configuration

OpenID

By default openQA uses the opensuse.org OpenID provider to authenticate users. If you want to change that, you can do it in /etc/openqa/openqa.ini. The first user that logs in (if there is no admin yet) will automatically get admin and operator rights. As admin you need to do some further actions to get your openQA instance testing software.

SSL

By default openQA expects to be run with HTTPS. If you don’t have an SSL certificate for your host you need to turn HTTPS off. You can do that in /etc/openqa/openqa.ini:

[openid]
httpsonly = 0

Running workers

Workers are processes running virtual machines to perform the actual testing. To allow them to access your instance, you need to log into openQA as operator and create a pair of API key and secret. Once you are logged in, follow the link manage API keys in the top right corner. Click the create button to generate key and secret. Copy&paste them into /etc/openqa/client.conf. Make sure to put in a section reflecting your webserver URL. In the simplemost case, your client.conf may look like this:

[localhost]
key = 0123456789ABCDEF
secret = 0123456789ABCDEF

To start the workers you can use the provided systemd files via systemctl start openqa-worker@1. This will start worker number one. You can start as many workers as you dare, you just need to supply different worker id (number after @).

You can also run workers manually from command line.

sudo -u geekotest /usr/share/openqa/script/worker --instance X

This will run a worker manually showing you debug output. If you haven’t installed os-autoinst from packages make sure to pass --isotovideo option to point to the checkout dir where isotovideo is, not to /usr/lib! Otherwise it will have trouble finding its perl modules.

Apache proxy

It’s recommended to run openQA behind an apache proxy. See openqa.conf.template config file in /etc/apache2/vhosts.d. To make everything work correctly, you need to enable the proxy_http, headers and proxy modules using a2enmod.

Advanced configuration

Setting up git support

Editing needles from web can optionally commit new or changed needles automatically to git. To do so, you need to enable git support by setting

[global]
scm = git

in /etc/openqa/openqa.ini. Once you do so and restart the web interface, openQA will automatically commit new needles to the git repository.

You may want to add some description to automatic commits coming from the web UI. You can do so by setting your configuration in the repository (/var/lib/os-autoinst/needles/.git/config) to some reasonable defaults such as:

[user]
	email = [email protected]
	name = openQA web UI

To enable automatic pushing of the repo as well, you need to add the following to your openqa.ini:

[scm git]
do_push = yes

Depending on your setup, you might need to generate and propagate ssh keys for user geekotest to be able to push.

Worker settings

Default behaviour for all workers is to use the Qemu backend and connect to http://localhost. If you want to change some of those options, you can do so in /etc/openqa/workers.ini. For example if you want to connect to the port 9526 (default port after installation if you haven’t set up Apache proxy), you can do so using following code:

[global]
HOST = http://localhost:9526

Once you got workers running they should show up in the admin section of openQA in the workers section as idle. When you get so far, you have your own instance of openQA up and running and all that is left is to set up some tests.

Filesystem Layout

The openQA web interface can be started via MOJO_REVERSE_PROXY=1 morbo script/openqa in development mode.

/var/lib/openqa/ must be owned by root and contain several sub directories owned by the user that runs the workers (default geekotest):

  • backlog

  • cache (cache directory, needs to be owned by the user who runs openqa)

  • factory/iso

  • perl/ (subdirectory autoinst must link to /usr/lib/os-autoinst)

  • pool/1 (add more for each worker)

  • testresults

  • tools (symlink to /usr/share/openqa/tools/)

/var/lib/openqa/db contains the sqlite database and must be owned by the user that runs the web interface (geekotest). To initially create this database, you need to run tools/initdb.

Troubleshooting

Tests fail quickly

Check the log files in /var/lib/openqa/testresults

KVM doesn’t work

  • make sure you have a machine with kvm support

  • make sure kvm_intel or kvm_amd modules are loaded

  • make sure you do have virtualization enabled in BIOS

  • make sure the geekotest user can access /dev/kvm

  • make sure you are not already running other hypervisors such as VirtualBox