A more recent version is now officially available on https://openqa.debian.net/work_on_tests.html

In order to be able to create new tests or to improve/modify existing tests, you’ll need to have your own fork of the test repository. If you are a Debian Developers, you can skip the forking step.

These instructions assume that you are using a virtual machine, as configured https://rclobus.nl/blog/?p=440

Prepare the git workspace

1. The key, that is used locally for Ansible, can be re-purposed for use on Salsa too (user=user)
   cat ~/.ssh/id_ed25519.pub
2. Paste the output of the last command in ‘SSH Keys’ for Salsa (https://salsa.debian.org/-/user_settings/ssh_keys)
3. Create a fork in Salsa
   • Go to https://salsa.debian.org/qa/openqa/openqa-tests-debian
   • Click on ‘Fork’
   • ‘Select a namespace’ -> your username on salsa
   • ‘Branches to include’ -> ‘Only the default branch debian’
   • Click on ‘Fork project’
4. Install additional packages for the coding convention (user=root)
   apt-get install --yes make perltidy
5. Add your user to the group that owns the git workspace (user=root)
   usermod --append --groups geekotest user
6. Activate the new group membership -> logout and login again
7. Add your fork to the local git workspace (user=user)
   cd /var/lib/openqa/share/tests/debian
git config --global --add safe.directory /var/lib/openqa/share/tests/debian
SALSA_USERNAME=enter your username for salsa here
git remote add mine git@salsa.debian.org:${SALSA_USERNAME}/openqa-tests-debian.git
git fetch --all
8. Tell git who you are (user=user)
   git config --global user.email "you@example.com"
git config --global user.name "Your Name"
9. Work with git as usual to prepare the update
   git checkout origin/debian
git switch -c ${SALSA_USERNAME}/featurename
git add some_modified_file
10. Always apply the Perl coding convention before doing a commit (user=user)
    make tidy
11. Publish your changes and create a merge request (user=user)
    git commit
git push --set-upstream origin ${SALSA_USERNAME}/featurename
12. Merge requests on Salsa are monitored, so your change will be reviewed and merged soon

Monitor a job and perform needle updates

1. Install additional packages (user=root)
   apt-get install --yes tigervnc-viewer
2. Browse to a running job on http://localhost
3. Go to the tab ‘Live View’
4. Click on ‘Developer Mode’
5. Change ‘Pause on screen mismatch’ to ‘assert_screen timeout’
6. Click on ‘Confirm to control this test’
7. See also the documentation of upstream: Use of the web interface

A more recent version is now officially available on https://openqa.debian.net/install.html

Previously, I’ve modified the blog post from 2022-01 to update the installation to bookworm. This is a rewrite, based on trixie.

Steps to install openQA (a local copy of openqa.debian.net)

The goal is to install openQA in a local virtual machine with the capacity to run 2 workers.

Prepare the openQA server

1. Use qemu with a recent netinst image (at time of writing: trixie 13.1.0 from here). The (non-default) settings for qemu are:
   • Memory: 8192MiB (this is enough for openqa (1GiB), 1 big (4GiB) and 1 small worker (2GiB)
   • Storage: 80GiB HD, Disk bus=SATA
   • Add Hardware/Filesystem: Driver=virtio-9p, Source path=/media/fast Target path=/external_iso_files, Export filesystem as readonly mount=Checked
2. Install to the harddisk, using the default answers, except for the following:
   • Region: matching my own region and country, but still using en_US.UTF-8 as locale
   • Username: user
   • Hostname: openqa
   • Proxy: http://192.168.122.1:3142 (my local apt-cacher-ng)
   • Software: GNOME + ssh server
3. Use dep822 for apt (user=root)
   apt --yes modernize-sources
rm /etc/apt/sources.list~
rm /etc/apt/sources.list.bak
4. Prepare to use fasttrack.debian.net (user=root)
   apt-get install fasttrack-archive-keyring
5. Activate fasttrack.debian.net (user=root)
   cat << EOF > /etc/apt/sources.list.d/fasttrack.sources
Types: deb
URIs: https://fasttrack.debian.net/debian-fasttrack/
Suites: trixie-fasttrack
Components: main
Signed-By: /usr/share/keyrings/fasttrack-archive-keyring.gpg
EOF
6. Install required and preferred packages (user=root)
   rm /etc/apt/apt.conf # This contains the proxy that was used during the installer
apt-get update # Update the package list
apt-get install auto-apt-proxy
apt-get install aptitude # For looking at package dependencies etc.
apt-get install --yes ansible ssh-askpass rsync # For the configuration of the openqa server
7. Install the Debian package openqa and friends (user=root)
   apt-get install --yes -t trixie-fasttrack openqa openqa-worker
8. Configure openqa (for non-ssl) (user=root)
   /usr/share/openqa/script/configure-web-proxy
a2dissite 000-default
a2ensite openqa
systemctl reload apache2
9. Configure the login procedure (user=root)
   cat << EOF > /etc/openqa/openqa.ini.d/50-download_domains.ini
[global]
# Allowed domains for ISO_URL
download_domains = reproducible-builds.org debian.org
EOF
cat << EOF > /etc/openqa/openqa.ini.d/50-auth.ini
[auth]
# Simple authentication
method = Fake
EOF
10. Apply the Debian branding (user=root)
    mkdir -p /usr/share/openqa/templates/webapi/branding/openqa.debian.net
cat << EOF > /usr/share/openqa/templates/webapi/branding/openqa.debian.net/sponsorbox.html.ep
<div class="text-end" id="sponsorbox">
<a href="https://www.debian.org" title="Debian"> <img alt="Debian" src="https://www.debian.org/logos/openlogo.svg"> </a>
</div>
EOF
cat << EOF > /usr/share/openqa/templates/webapi/branding/openqa.debian.net/docbox.html.ep
<h1>Welcome to the openQA instance of Debian</h1>
<p>Life is too short for manual testing!</p>
<p><a class="btn btn-primary btn-lg" href="http://open.qa" role="button">Learn more &#xbb;</a> <a class="btn btn-primary btn-lg" href="https://rclobus.nl/blog/?p=440" role="button">Install your own copy of openQA &#xbb;</a> <a class="btn btn-primary btn-lg" href="https://rclobus.nl/blog/?p=487" role="button">Work together on tests &#xbb;</a></p>
EOF
cat << EOF > /etc/openqa/openqa.ini.d/50-branding.ini
[global]
branding=openqa.debian.net
EOF
11. Restart the openQA webui (user=root)
    systemctl reload openqa-webui
12. Download and prepare the tests (user=root)
    su geekotest -s /bin/bash
cd /var/lib/openqa/share/tests
git clone https://salsa.debian.org/qa/openqa/openqa-tests-debian.git debian
ln -s debian debian-live
ln -s debian debian-edu
ln -s debian kali
ln -s debian windows
exit # To become root again
13. (Re-)generate the default API key on the openQA server, valid for 24 hours (user=user)
    openqa-cli api --apibase http://localhost -X GET login | grep "Logged in as"
14. Configure the API key, to avoid providing the values on each openqa-cli command (user=user)
    mkdir ~/.config/openqa
cat << EOF >> ~/.config/openqa/client.conf
[localhost]
key = 1234567890ABCDEF
secret = 1234567890ABCDEF
EOF
15. Create a new SSH key for Ansible (user=user)
    ssh-keygen -t ed25519 -C "VM Debian-openQA"
cat ~/.ssh/id_ed25519.pub >> ~/.ssh/authorized_keys
ssh localhost # Accept the fingerprint with 'yes'
exit # Close the ssh connection
16. Configure the openQA server using Ansible (user=user)
    cd /var/lib/openqa/share/tests/debian/configuration
# Ugly, needs improvement: create the groups manually and remove the deleted ids
# At the time of writing this, the highest id was 24
for i in $(seq 1 24); do openqa-cli api -X POST job_groups name=dummy_group$i; done
for i in $(seq 1 9) 15; do openqa-cli api -X DELETE job_groups/$i; done
ansible-playbook configure_openqa.yaml -i server_localhost.yaml
17. Mount the pre-existing ISOs that have been made available in qemu (user=root)
    echo "/external_iso_files /var/lib/openqa/share/factory/iso 9p trans=virtio,ro 0 0" >> /etc/fstab
systemctl daemon-reload
mount /var/lib/openqa/share/factory/iso
    Note: this mount point must be unmounted before updating openqa with apt-get

Prepare the openqa-worker

1. Disable the (currently) not needed slirp VDE service (user=root)
   systemctl disable openqa-slirpvde
2. Use the proxy when running installers under openQA (user=root)
   cat << EOF > /etc/openqa/workers.ini.d/50-http_proxy.ini
[global]
# Use the proxy (apt-cacher-ng) from the host
HTTP_PROXY = http://192.168.122.1:3142/
# The value http://localhost:9/ could be used for a 'network-access-denied' setting
EOF
3. Configure worker 2 with more memory (user=root)
   cat << EOF > /etc/openqa/workers.ini.d/55-bigmem-worker.ini
# x86_64 worker for jobs that require more memory
[2]
WORKER_CLASS=qemu_x86_64,qemu_x86_64_bigmem
EOF
4. Configure a worker for arm64 (via emulation, slow!) (user=root)
   cat << EOF > /etc/openqa/workers.ini.d/60-arm-worker.ini
# arm64 worker
[10]
WORKER_CLASS=qemu_aarch64
QEMU_NO_KVM=1
QEMUCPU=max
QEMUMACHINE=virt,usb=off
EOF
5. Configure the secrets (user=root)
   cat << EOF > /etc/openqa/client.conf
[localhost]
key = 1234567890ABCDEF
secret = 1234567890ABCDEF
EOF
chown _openqa-worker /etc/openqa/client.conf
chmod 0400 /etc/openqa/client.conf
6. Start the cache service (user=root)
   systemctl restart openqa-worker-cacheservice
systemctl restart openqa-worker-cacheservice-minion
7. Enable the workers (user=root)
   systemctl enable openqa-worker@1
systemctl enable openqa-worker@2
systemctl enable openqa-worker@10
8. Start the workers (user=root)
   systemctl start openqa-worker@1
systemctl start openqa-worker@2
systemctl start openqa-worker@10

Run the first tests

Basic test (amd64)

1. Download the netinst image (on the host)
   cd /media/fast
wcurl https://cdimage.debian.org/debian-cd/current/amd64/iso-cd/debian-13.1.0-amd64-netinst.iso
2. Run the netinst tests (user=user)
openqa-cli api -X POST isos ISO=debian-13.1.0-amd64-netinst.iso DISTRI=debian VERSION=stable FLAVOR=netinst-iso ARCH=x86_64 BUILD=1310

Cross-test (arm64)

1. Install the suitable qemu package (user=root)
   apt-get install qemu-system-arm
2. Download the netinst image (on the host)
   cd /media/fast
wcurl https://cdimage.debian.org/debian-cd/current/arm64/iso-cd/debian-13.1.0-arm64-netinst.iso
3. Run the netinst tests (user=user)
openqa-cli api -X POST isos ISO=debian-13.1.0-arm64-netinst.iso DISTRI=debian VERSION=stable FLAVOR=netinst-iso ARCH=aarch64 BUILD=1310

A live image (amd64)

1. Download the live image (on the host)
   cd /media/fast
wcurl https://get.debian.org/images/release/current-live/amd64/iso-hybrid/debian-live-13.1.0-amd64-gnome.iso
2. Run the tests (user=user)
   openqa-cli api -X POST isos ISO=debian-live-13.1.0-amd64-gnome.iso DISTRI=debian-live VERSION=trixie FLAVOR=gnome ARCH=x86_64 BUILD=1310 CHECKSUM=1886e3fcfdbe60d01ed5e878e143e56ca0443afa8a655404cf3bc057f39a622c

Look at the running builds in openQA

Start firefox and go to ‘http://localhost’ (not https)

Reset the openQA database (to be able to redo some steps)

If you need to reset the database and start from scratch (but you can keep the installed packages and configuration) follow the next steps.

Warning: this will remove all content from the database

1. Stop all services (user=root)
   systemctl stop openqa-webui
systemctl stop openqa-gru
systemctl stop openqa-websockets
systemctl stop openqa-scheduler
2. Drop the database (user=geekotest)
   dropdb openqa
   There should not be a line like ‘DETAIL: There are N other sessions using the database.’, otherwise a few more openqa-related services need to be stopped
3. Regenerate the empty database (user=root)
   systemctl start openqa-webui
4. Redo the steps with Ansible (see above)

Assumptions

In this blog article, I’ve made the following assumptions:

• On the host, the ISO files are stored in /media/fast
• On the host, apt-cacher-ng is running and available inside the VM at 192.168.122.1:3142

Missing sections

• Example command line for cloning an existing job from openqa.debian.net

What’s next?

Create and modify tests: https://rclobus.nl/blog/?p=487