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. All its dependencies are available on Debian 12 ‘bookworm’ or Debian 11 ‘bullseye’ (using bullseye-backports).

The latest development packages can be installed via apt using the debusine repository intended for testing and development, containing the latest build from devel branch.

$ curl -s https://freexian-team.pages.debian.net/debusine/repository/public-key.asc \
  | sudo tee /etc/apt/trusted.gpg.d/debusine.asc
$ echo "deb [arch=all] https://freexian-team.pages.debian.net/debusine/repository/ bookworm main" \
  | sudo tee /etc/apt/sources.list.d/debusine.list
$ sudo apt update
$ sudo apt install debusine-server

To set up bullseye-backports if needed:

# Only needed on Bullseye
$ 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 .
Debusine server has many configuration options. Review the documentation in /etc/debusine/server/*. If you need to use your own local settings instead of the default ones create a local.py file:
```
$ sudo cp -i /etc/debusine/server/local.py.sample \
   /etc/debusine/server/local.py
```
And edit the file /etc/debusine/server/local.py.

Note that you can choose which type of settings are running. By default, selected.py is a symbolic link to production.py, but this can be changed to development.py.

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 debusine-admin commands and the Debusine specific ones. The Debusine specific commands are under the [server] section:

[server]
  create_notification_channel
  create_token
  create_user
  delete_expired_artifacts
  delete_notification_channel
  delete_tokens
  edit_worker_metadata
  list_notification_channels
  list_tokens
  list_users
  list_work_requests
  list_workers
  manage_notification_channel
  manage_token
  manage_user
  manage_worker
  monthly_cleanup

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: check /var/log/debusine/server/ files and read the next section for the email settings.

Configuration for sending emails

Enable the local.py settings file if not done before:

$ # if you have not enabled using local.py before:
$ cp -i /etc/debusine/server/local.py.sample /etc/debusine/server/local.py

By default, Django, sends emails using the local MTA. You can use any SMTP server. For example, edit /etc/debusine/server/local.py and add:

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.

See the section testing sending emails to send a test email.

When the test email works: restart debusine-server so the new settings are applied:

Creating channel to send emails

Channels are created by the debusine admin and can be used by debusine clients to set up email notifications.

To create a notification channel with the name lts and type email (the only supported channel type at the moment) to send emails to lts@example.com and subject Debusine work request {work_request_id}: {work_request_result}.

$ sudo -u debusine-server debusine-admin create_notification_channel lts email << EOF
{
  "from": "admin@example.com",
  "to": ["lts@example.com"]
}
EOF

from and to are required fields. cc (list of emails) and subject are optional fields. The default subject is WorkRequest {work_request_id} completed in {work_request_result}, and the {work_request_id} and {work_request_result} are replaced by the id and result (success, failure or error)

Related commands of create_notification_channel are delete_notification_channel, list_notification_channels or manage_notification_channel.

Refer to the debusine-client documentation to create a work request with notifications to create a work request using a channel.

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, set DEBUSINE_FQDN in debusine settings:
$ # if you have not enabled using local.py before:
$ cp -i /etc/debusine/server/local.py.sample /etc/debusine/server/local.py
$ # Then edit the file
$ sudo editor /etc/debusine/server/local.py
Set the DEBUSINE_FQDN to your VirtualHost.

(for testing, you could have a line such as: ALLOWED_HOSTS = ["*"], but do not use it in production)
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 debusine-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).