From: Roland Clobus <rclobus@rclobus.nl>
Date: Mon, 23 May 2022 18:23:14 +0200
Subject: Debian specific documentation

---
 docs/GettingStarted.asciidoc | 69 ++++++++++++++++++++++++++++++++++++++++----
 docs/Installing.asciidoc     | 33 ++++++++++++++++++---
 2 files changed, 93 insertions(+), 9 deletions(-)

diff --git a/docs/GettingStarted.asciidoc b/docs/GettingStarted.asciidoc
index a6e9328..b26172e 100644
--- a/docs/GettingStarted.asciidoc
+++ b/docs/GettingStarted.asciidoc
@@ -388,9 +388,9 @@ The personal configuration should be stored in a file
 the `client.conf`, i.e. sections for each machine, e.g. `localhost`.
 
 [[get-testing]]
-== Testing openSUSE or Fedora
+== Testing openSUSE, Fedora or Debian
 
-An easy way to start using openQA is to start testing openSUSE or Fedora as they
+An easy way to start using openQA is to start testing openSUSE, Fedora or Debian as they
 have everything setup and prepared to ease the initial deployment. If you want
 to play deeper, you can configure the whole openQA manually from scratch, but
 this document should help you to get started faster.
@@ -403,6 +403,13 @@ Otherwise you will need to clone tests and needles manually. For this,
 clone a subdirectory under `/var/lib/openqa/tests` for each test distribution
 you need, e.g. `/var/lib/openqa/tests/opensuse` for openSUSE tests.
 
+==== OpenSUSE
+
+You can get openSUSE tests and needles (the expected results) from
+https://github.com/os-autoinst/os-autoinst-distri-opensuse[GitHub]. It belongs
+into the `/var/lib/openqa/tests/opensuse` directory. To make it easier, you can just
+run
+
 The repositories will be kept up-to-date if `git_auto_update` is enabled in
 <<GettingStarted.asciidoc#_configuration,the web UI configuration>> (which is the
 default). The updating is triggered when new tests are scheduled. For a periodic
@@ -414,9 +421,10 @@ https://github.com/os-autoinst/os-autoinst-distri-opensuse[GitHub]. To make it
 easier, you can just run `/usr/share/openqa/script/fetchneedles`. It will
 download tests and needles to the correct location with the correct permissions.
 
-Fedora's tests are also in
-https://pagure.io/fedora-qa/os-autoinst-distri-fedora[git]. To use them, you may
-do:
+==== Fedora
+
+Fedora's tests are also in https://pagure.io/fedora-qa/os-autoinst-distri-fedora[git]. To
+use them, you may do:
 
 [source,sh]
 --------------------------------------------------------------------------------
@@ -428,6 +436,31 @@ cd ..
 chown -R geekotest fedora/
 --------------------------------------------------------------------------------
 
+==== Debian
+
+Debian's tests are in https://salsa.debian.org/qa/openqa/openqa-tests-debian.git[git]. To use them, you may do:
+
+NOTE: Roland: Phil, 'fetchneedles' is distributed as part of openqa-common. When I ran it for the first time, it tried to create '/var/lib/openqa/.ssh/known_hosts'. That was possible only after I did 'chown geekotest /var/lib/openqa'. What is the preferred workflow? Use 'fetchneedles' or run the commands directly? i.e. can the Debian instruction become: 'run fetchneedles, just like openSUSE?'
+NOTE: Roland: Phil, can 'python3-jsonschema' become a dependency of openqa-common? (i.e. to allow 'fifloader.py' to run)
+
+[source,sh]
+--------------------------------------------------------------------------------
+# Run as root. Method 1 with fetchneedles
+apt-get install python3-jsonschema ## Can this be integrated in the package openqa-common?
+/usr/share/openqa/script/fetchneedles
+cd /var/lib/openqa/share/tests/debian
+./fifloader.py templates.fif.json --load --clean ## Can this be integrated into fetchneedles?
+
+# Run as root Method 2 without fetchneedles
+apt-get install python3-jsonschema
+cd /var/lib/openqa/share/tests
+git clone https://salsa.debian.org/qa/openqa/openqa-tests-debian.git debian
+cd debian
+./fifloader.py templates.fif.json --load --clean
+cd ..
+chown -R geekotest debian/
+--------------------------------------------------------------------------------
+
 === Getting openQA configuration
 
 To get everything configured to actually run the tests, there are plenty of
@@ -447,6 +480,9 @@ consider reading its help page (`--help`) for documentation on possible extra ar
 
 For Fedora, similarly, you can call:
 
+NOTE: Roland: Fedora team, this is outdated. There is no file 'templates' in your repo any more.
+NOTE: Roland: It is probably as in Debian: './fifloader.py templates.fif.json --load --update'
+
 [source,sh]
 --------------------------------------------------------------------------------
 /var/lib/openqa/share/tests/fedora/fifloader.py -c -l templates.fif.json templates-updates.fif.json
@@ -464,6 +500,13 @@ https://pagure.io/fedora-qa/createhdds[createhdds]
 repository can be used to create these. See the documentation in that repo
 for more information.
 
+For Debian, you can call:
+
+[source,sh]
+--------------------------------------------------------------------------------
+./fifloader.py templates.fif.json --load --update
+--------------------------------------------------------------------------------
+
 === Adding a new ISO to test
 
 To start testing a new ISO put it in `/var/lib/openqa/share/factory/iso` and call
@@ -503,6 +546,22 @@ openqa-cli api -X POST isos \
          BUILD=Rawhide-20160308.n.0
 --------------------------------------------------------------------------------
 
+For Debian, a sample run might be:
+
+NOTE: Roland: should these 3 examples be simplified? They are nearly duplicates
+
+[source,sh]
+--------------------------------------------------------------------------------
+# Run the first test
+openqa-cli api -X POST isos \
+         ISO=debian-testing-amd64-netinst.iso \
+         DISTRI=debian \
+         VERSION=testing \
+         FLAVOR=netinst-iso \
+         ARCH=x86_64 \
+         BUILD=20220310_0422-testing-amd64
+--------------------------------------------------------------------------------
+
 More details on triggering tests can also be found in the
 <<UsersGuide.asciidoc#usersguide,Users Guide>>.
 
diff --git a/docs/Installing.asciidoc b/docs/Installing.asciidoc
index 23810f4..f3bd1c8 100644
--- a/docs/Installing.asciidoc
+++ b/docs/Installing.asciidoc
@@ -294,6 +294,7 @@ The easiest way to install openQA is from distribution packages.
   available.
 - For Fedora, packages are available in the official repositories for Fedora
   23 and later.
+- For Debian, packages are available in the official repositories for Debian Bookworm and later.
 
 === Development version repository
 
@@ -352,6 +353,9 @@ zypper in openQA
 
 # Fedora
 dnf install openqa openqa-httpd
+
+# Debian
+apt-get install openqa
 -------------------------------------------------------------------------------
 
 To install the openQA worker package use the following.
@@ -360,6 +364,9 @@ To install the openQA worker package use the following.
 -------------------------------------------------------------------------------
 # SLE/openSUSE
 zypper in openQA-worker
+
+# Debian
+apt-get install openqa-worker
 -------------------------------------------------------------------------------
 
 Different convenience packages exist for convenience in openSUSE, for example:
@@ -423,19 +430,30 @@ If you wish to run openQA behind an http proxy (Apache, NGINX, …) then see the
 
 === Apache proxy
 
-To make everything work correctly on openSUSE when using Apache, you
+To make everything work correctly on openSUSE or Debian when using Apache, you
 need to enable the 'headers', 'proxy', 'proxy_http', 'proxy_wstunnel' and 'rewrite'
-modules using the command 'a2enmod'. This is not necessary on Fedora.
+modules using the command 'a2enmod'. On Debian you'll additionally need 'expires'.
+
+This is not necessary on Fedora.
 
 [source,sh]
 --------------------------------------------------------------------------------
-# openSUSE Only
+# openSUSE
+# You can check what modules are enabled by using 'a2enmod -l'
+a2enmod headers
+a2enmod proxy
+a2enmod proxy_http
+a2enmod proxy_wstunnel
+a2enmod rewrite
+
+# Debian
 # You can check what modules are enabled by using 'a2enmod -l'
 a2enmod headers
 a2enmod proxy
 a2enmod proxy_http
 a2enmod proxy_wstunnel
 a2enmod rewrite
+a2enmod expires
 --------------------------------------------------------------------------------
 
 For a basic setup, you can copy *openqa.conf.template* to *openqa.conf*
@@ -444,7 +462,11 @@ This will direct all HTTP traffic to openQA.
 
 [source,sh]
 --------------------------------------------------------------------------------
+# openSUSE
 cp /etc/apache2/vhosts.d/openqa.conf.template /etc/apache2/vhosts.d/openqa.conf
+
+# Debian
+cp /etc/apache2/sites-available/openqa.conf.template /etc/apache2/sites-enabled/openqa.conf
 --------------------------------------------------------------------------------
 
 === NGINX proxy
@@ -1033,13 +1055,16 @@ is mounted. Example:
 [source,ini]
 --------------------------------------------------------------------------------
 [global]
-HOST = openqa.opensuse.org openqa.fedora.fedoraproject.org
+HOST = openqa.opensuse.org openqa.fedoraproject.org openqa.debian.net
 
 [openqa.opensuse.org]
 SHARE_DIRECTORY = /var/lib/openqa/opensuse
 
 [openqa.fedoraproject.org]
 SHARE_DIRECTORY = /var/lib/openqa/fedora
+
+[openqa.debian.net]
+SHARE_DIRECTORY = /var/lib/openqa/debian
 --------------------------------------------------------------------------------
 
 Configuring `SHARE_DIRECTORY` is not a hard requirement. Workers will try following