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:

$ 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 What the 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:
```
$ 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:

$ sudo -u debusine-server debusine-admin migrate

Commands can be issued to the server, for example:
```
$ sudo -u debusine-server debusine-admin list_tokens
```
To see the list of commands:
```
$ 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:

$ 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:

$ 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:

$ 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:

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:
$ 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:
$ 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:
$ 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:
$ sudo rm /etc/nginx/sites-enabled/default
Restart Nginx:
$ sudo systemctl restart nginx
If the server’s hostname does not match the HTTP VirtualHost, add ALLOWED_HOSTS in debusine settings:
$ 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:
$ echo 'DEFAULT_FROM_EMAIL = "noreply@example.com"'
Restart to apply the new settings:
$ 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 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).