Setup of osc-collab server for the openSUSE project
===================================================

The server runs on the osc-collab virtual machine.

When updating the code or data in git, you will need to update the files on
the virtual machine too. We could automatically update the code from git, but
it wouldn't be very safe to do unattended updates without looking at the
changes in git.

Just ask one of the osc-collab admins to do the following on the osc-collab
virtual machine:

  # check changes in git are fine, if yes then update the code
  su - opensuse-scripts
  cd ~/src/osc-plugin-collab; git pull


High-level overview
===================

The runme scripts are run by wrapper scripts that cron will execute every 20
minutes. The order in which these wrapper scripts are run matters, as the data
generated by one script can be used by another. The recommended order is:

 1. getting upstream data
 2. update the database
 3. modify OBS attributes

See the crontab file for a potential setup.

The wrapper scripts live in the cron-scripts/ subdirectory. There is one wrapper
script for each task, and a common file for shared functions/settings.

The wrapper scripts will make use of a obs.conf configuration file. See the
collab-data/ subdirectory for an example.

Log files from the log wrappers will be located in the cron-scripts/logs/
subdirectory.


Configuration that has to be done
=================================

Obviously, osc must be installed and configured for the specific user that will
be used by the scripts. It is also recommended to have the python-lxml module
installed, for performance reasons. Other required packages include: bc, curl,
dotlockfile or withlock.

Then, several files need to be updated:

crontab:
  The MAILTO variable contains the mail address that will receive errors.

collab-data/obs.conf:
  The cache-dir variable should be updated to reflect where the cache directory
  will be.

cron-scripts/common:
  Several variables control the configuration of the wrapper scripts:
    WATCHDOG_CMD: command for a script that will kill processes that are stuck.
                  This can be ignored if needed.
    COLLAB_DATA_DIR: directory that contains obs.conf and the cache
                     subdirectory. Must be set.
    OBS_CONF: can be used to override the location of obs.conf. Must be set, but
              suggested value should be correct.
    OSC_PLUGIN_COLLAB_DIR: directory that contains the osc-plugin-collab code.
                           Must be set.
    OBS_UPLOAD_URL: URL to obs-upload.py from the web API. If left empty, the
                    obs.db database won't get uploaded. This is generally fine
                    for a setup where the web server lives on the same machine
                    as the cron scripts.


Note for osc-collab admins
==========================

The major task for osc-collab admins is to make sure the server is correctly
configured, and the osc-collab server code runs fine.

The infrastructure team will handle maintenance of the virtual machine. Non
interactive updates are usually automatically installed, and kernel updates are
manually dealt with.

A new osc-collab admin should contact the openSUSE infrastructure team so that
the team knows about the new osc-collab admin.
