.. _setting-up-debusine-server:

==========================
Setting up debusine-server
==========================

Introduction
------------

Debusine server waits for workers to connect and receives work requests
from the clients. When a work request is received by the server it tries
to match a worker for it and sends the work request to the worker.

Initial setup
-------------

Install the ``debusine-server`` package. It depends on packages available
on Bullseye with the exception of the ``python3-django`` which is available on
``bullseye-backports``.

To set up bullseye-backports if needed:

.. code-block:: console

  $ echo "deb http://deb.debian.org/debian bullseye-backports main" | sudo tee /etc/apt/sources.list.d/bullseye-backports.list
  $ sudo apt update
  $ sudo apt install python3-django/bullseye-backports

To know what the package does during
installation see the :ref:`What the package does on installation
<what-debusine-server-package-does-on-installation>` section.


Follow the steps below to finalize the set-up:
  #. By default, the package is configured to use a PostgreSQL database
     using the default local Unix socket and the authentication is done at
     the user level. The package creates a "debusine-server" Unix account.
     Create a "debusine" database that can be managed by the
     "debusine-server" user. This can be done with:

     .. code-block:: console

       $ sudo apt install postgresql redis # if you need to install Postgresql/redis
       $ sudo -u postgres createuser debusine-server
       $ sudo -u postgres createdb --owner debusine-server debusine

     The database configuration can be edited in
     ``/etc/debusine/server/db_postgresql.py`` .

  #. The Debusine Server has many configuration options. Review
     the documentation in ``/etc/debusine/server/*`` and update
     ``/etc/debusine/server/local.py`` if needed.

  #. Initialize the database:

     .. code-block:: console

       $ sudo -u debusine-server debusine-admin migrate

  #. Commands can be issued to the server, for example:

     .. code-block:: console

       $ sudo -u debusine-server debusine-admin list_tokens

     To see the list of commands:

     .. code-block:: console

       $ sudo -u debusine-server debusine-admin help

     The debusine specific commands are under the ``[server]`` section.

  #. Configure a webserver (see below for details on how to use
     Nginx with the default setup of debusine-server using daphne).


Debusine server commands
------------------------
``debusine-server`` package provides the command ``debusine-admin``. In the default
configuration it is needed to run the command using the ``debusine-server``
user. The main reason is the default authentication for the ``debusine``
PostgreSQL database. A secondary reason are the permissions of the log
files: only writable by ``debusine-server`` command.

To see the list of commands:

.. code-block:: console

  $ sudo -u debusine-server debusine-admin

It will list all the django-admin commands and the Debusine specific ones. The
Debusine specific commands are under the ``[server]`` section::

  [server]
    create_token
    edit_worker_metadata
    list_tokens
    list_workers
    manage_token
    manage_worker
    remove_tokens

You can see the command specific help using ``--help``, for example:

.. code-block:: console

  $ sudo -u debusine-server debusine-admin create_token --help

Testing sending emails
----------------------

``debusine-server`` can send emails when certain events happen. For example,
if a work request fails, it can send an email to notify the user that there is
a problem.

By default, ``debusine-server`` uses the local MTA. To test if it can send,
execute the command:

.. code-block:: console

  $ sudo -u debusine-server debusine-admin sendtestemail destination@example.com

If the email is not delivered, ``/var/log/debusine/server/`` files
and the next section for the email settings.

Configuration for sending emails
--------------------------------

Use Django's ``EMAIL_*`` settings as specified in the
`Django documentation email settings`_.

For example:

.. code-block:: python3

  DEFAULT_FROM_EMAIL = "noreply@example.com"
  EMAIL_HOST = "smtp.example.com"
  EMAIL_PORT = 587
  EMAIL_HOST_USER = "user"
  EMAIL_HOST_PASSWORD = "the_password"
  EMAIL_USE_TLS = True

More settings are available in the `Django documentation email settings`_.

Configuration with Nginx
------------------------

The package provides a ``debusine-server.service`` unit for systemd
that will run Daphne (HTTP/HTTP2/WebSocket protocol server) and make
Debusine available on ``/var/lib/debusine/server/daphne.sock`` . There
is also a ready-to-use Nginx virtual host pointing to the ``daphne.sock``
file to make it available.

  #. Install (or create) the Nginx configuration. ``debusine-server`` package
     provides an example:
     
     .. code-block:: console

       $ sudo apt install nginx
       $ sudo cp /usr/share/doc/debusine-server/examples/nginx-vhost.conf \
            /etc/nginx/sites-available/debusine.example.net

     Change the variable "server_name" by the correct one. For testing, if the only
     "site-available" in Nginx is debusine the default ``localhost`` can be left. It is
     possible to access debusine via IP. Otherwise edit the file:

     .. code-block:: console

       $ sudo editor /etc/nginx/sites-available/debusine.example.net

     Search for "server_name" and change its value.

  #. Enable the Nginx configuration for the Debusine server:

     .. code-block:: console

       $ sudo ln -sf /etc/nginx/sites-available/debusine.example.net /etc/nginx/sites-enabled

     When setting up a new server, the default Nginx server configuration
     may need to be deleted:

     .. code-block:: console

       $ sudo rm /etc/nginx/sites-enabled/default

  #. Restart Nginx:

     .. code-block:: console

       $ sudo systemctl restart nginx

  #. If the server's hostname does not match the HTTP VirtualHost, add
     ALLOWED_HOSTS in debusine settings:

     .. code-block:: console

       $ echo 'ALLOWED_HOSTS = ["your_virtual_host"]' | sudo tee -a /etc/debusine/server/selected.py

     (for testing, ``ALLOWED_HOSTS = ["*"]`` could be used, but do not use it
     in production)

  #. Specify the default from email in the configuration:

     .. code-block:: console

       $ echo 'DEFAULT_FROM_EMAIL = "noreply@example.com"'

  #. Restart to apply the new settings:

     .. code-block:: console

       $ sudo systemctl restart debusine-server

  #. Verify that Debusine's welcome page loads on ``http://your_server`` (by name or IP).

     If the welcome page cannot be loaded please check ``/var/log/debusine/server`` and
     ``/var/log/nginx``.


.. _what-debusine-server-package-does-on-installation:

What the package does on installation
-------------------------------------

* Creates the ``debusine-server`` user
* Collects static files in ``/var/lib/debusine/server/static/``
  (to do this manually: ``sudo -u debusine-server debusine-admin collectstatic``)
* Provides ready-to-customize configuration files for Nginx/daphne
  (in ``/etc/nginx/sites-available/debusine-server``)
* Installs a systemd service (``debusine-server.service``) that uses Daphne to make the
  Debusine server available on ``/var/lib/debusine/server/daphne.sock``
* Creates the directories ``/var/log/debusine/server`` and ``/var/lib/debusine-server``
* Install a systemd timer unit to run monthly ``django-admin monthly_cleanup``.
  (see it using ``systemctl list-timers``, disable it for the next boot via
  ``systemctl disable debusine-server-monthly-cleanup.timer`` or stop it now
  ``systemctl stop debusine-server-monthly-cleanup.timer``).

.. _Django documentation email settings: https://docs.djangoproject.com/en/3.2/ref/settings/#email-host