README

Overview
========

The openQA framework consists of two parts, which are tracked in separate git
repos. The OS-autoinst test engine and the front-end with web-interface,
test-scheduler and other high-level logic, which is part of this repo.

Installation
============

The preferred way is to install openQA from packages. If you are not a
developer skip this section.

see devel:openQA/openQA on how to setup the software on openSUSE or run
tools/setup.sh for some help

openQA requires os-autoinst to be installed in /usr/lib/os-autoinst
(you can bind mount/symlink the git dir there)

FS Layout
---------

openQA web files (www/*) must be in /usr/share/openqa (again, can be bind
mounted/linked to git checkout).

/var/lib/openqa/ must be owned by root and contain several sub
directories owned by 'geekotest':

backlog
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 web
user. You need to run tools/initdb to create it.

configuring the web server
==========================

By default everything expects the openqa web stuff to run on
localhost. Please configure your apache accordingly (see config
files in etc/apache2).
You need to enable the 'rewrite' and 'headers' module (use a2enmod)

running workers
===============

To start the worker either use the provided systemd files (systemctl
start openqa-worker.target will start as many workers as you have
pool directories) or run tools/worker --instance X manually.
If you did not install os-autoinst from packages make sure to pass --isotovideo
to point to the checkout dir of isotovideo, not /usr/lib! It won't find the
perl modules then.

Place iso images you want to test in /var/lib/openqa/factory/iso/
Then run
/usr/share/openqa/tools/rpc.pl --host localhost iso_new FILE.ISO

Watch your workers (hopefully) picking up the jobs!

setting up git support
======================

cropimg may automatically commit new or changed needles to git. to
enable git support OPENQA_NEEDLES_SCM, OPENQA_NEEDLES_GIT_WORKTREE
and have to be set in the apache config. openQA will commit new
needles to the git repo then.

You may want to add something like this to the config of the git
repo (/var/lib/os-autoinst/needles/.git/config):
[user]
	email = whatever@example.com
	name = openQA web UI

To enable pushing the repo somewhere set OPENQA_NEEDLES_GIT_DO_PUSH
to "yes". You may need to generate an ssh key and put it in the
wwwrun home dir to be able to push.

troubleshooting
===============

the tests fail quickly
----------------------
check the log files in /var/lib/openqa/testresults

kvm doesn't work
----------------
1. make sure you a machine with kvm support
2. make sure kvm_intel or kvm_amd are loaded (might be disabled in the BIOS)
3. make sure the 'geekotest' user can access /dev/kvm