= WaiverDB SOP

WaiverDB is a service for recording waivers, from humans, that
correspond with results in ResultsDB.

On its own, it doesn't do much.

Importantly, the _Greenwave_ service queries resultsdb _and_ waiverdb
and makes decisions (for _Bodhi_ and other tools) based on the
combination of data from the two sources. A result in resultsdb may
matter, unless waived in waiverdb.

== Contact Information

Owner::
  Factory2 Team, Fedora QA Team, Infrastructure Team
Contact::
  #fedora-qa, #fedora-admin
Persons::
  dcallagh, gnaponie (giulia), lholecek, ralph (threebean)
Public addresses::
  * https://waiverdb-web-waiverdb.app.os.fedoraproject.org/api/v1.0/about
  * https://waiverdb-web-waiverdb.app.os.fedoraproject.org/api/v1.0/waivers
Servers::
  * In OpenShift.
Purpose::
  Record waivers and respond to queries about them.

== Description

See the https://waiverdb.readthedocs.io/en/latest/index.html[the upstream API docs for
detailed information]. The information here will be contextual to the
Fedora environment.

There _will be_ two ways of inserting waivers into waiverdb:

First, a cli tool, which performs a HTTP POST from the packager's
machine.

Second, a proxied request from bodhi. In this case, the packager will
click a button in the Bodhi UI (next to a failing test result). Bodhi
will receive the request from the user and in turn submit a POST to
waiverdb on the user's behalf. Here, the Bodhi Server will authenticate
_as_ the bodhi user, but request that the waiver be recorded as having
been submitted _by_ the original packager. Bodhi's account will have to
be given special _proxy_ privileges in waiverdb. See
https://pagure.io/waiverdb/issue/77

== Observing WaiverDB Behavior

Login to _os-master01.rdu3.fedoraproject.org_ as
_root_ (or authenticate remotely with openshift using
`oc login https://os.fedoraproject.org`, and run:

....
$ oc project waiverdb
$ oc status -v
$ oc logs -f dc/waiverdb-web
....

== Removing erroneous waivers

In general, don't do this. But if for some reason we _really_ need to,
the database for waiverdb lives outside of openshift in our standard
environment. Connect to db01:

....
[root@db01 ~][PROD]# sudo -u postgres psql waiverdb

waiverdb=# \d
              List of relations
 Schema |     Name      |   Type   |  Owner
--------+---------------+----------+----------
 public | waiver        | table    | waiverdb
 public | waiver_id_seq | sequence | waiverdb
(2 rows)

waiverdb=# select * from waiver;
....

Be careful. You can delete individual waivers with SQL.

== Upgrading

You can roll out configuration changes by changing the files in
https://pagure.io/fedora-infra/ansible/blob/main/f/roles/openshift-apps/waiverdb[roles/openshift-apps/waiverdb/]
and running the `playbooks/openshift-apps/waiverdb.yml` playbook.

To understand how the software is deployed, take a look at these two
files:

* `roles/openshift-apps/waiverdb/templates/imagestream.yml`
* `roles/openshift-apps/waiverdb/templates/buildconfig.yml`

See that we build a fedora-infra specific image on top of an app image
published by upstream. The _latest_ tag is automatically
deployed to staging. This should represent the latest commit to the
_master_ branch of the upstream git repo that passed its
unit and functional tests.

The _prod_ tag is manually controlled. To upgrade prod to
match what is in stage, move the _prod_ tag to point to the
same image as the _latest_ tag. Our buildconfig is
configured to poll that tag, so a new os.fp.o build and deployment
should be automatically created.

You can watch the build and deployment with _oc_ commands.

You can poll this URL to see what version is live at the moment:
https://waiverdb-web-waiverdb.app.os.fedoraproject.org/api/v1.0/about