Set up a debusine server

Introduction

The 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’ (using bookworm-backports).

$ sudo apt install postgresql redis # if you need to install Postgresql/redis
$ sudo apt install debusine-server

If needed configure APT with the appropriate package repository.

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.
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.
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).

You can run sudo -u debusine-server debusine-admin info to check that Debusine server configuration matches the expectations of your web server setup.

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
  delete_notification_channel
  delete_tokens
  edit_worker_metadata
  list_notification_channels
  list_tokens
  list_users
  list_work_requests
  list_workers
  manage_notification_channel
  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

The section debusine-admin command has documentation for each command.

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:

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

Configure Nginx with an HTTPS certificate

The example Nginx configuration used in the previous step listens on HTTPS as well as HTTP, using a locally-generated self-signed certificate. If you are happy connecting over HTTP, you can skip this section.

For a public Debusine server, you should change the ssl_certificate and ssl_certificate_key directives there to use a real certificate, for example via Let’s Encrypt. You might also wish to enforce the use of HTTPS by removing the listen directives for port 80.

Configure Nginx with an HTTPS certificate for a local development setup

This only makes sense if you need to deploy Debusine locally on machines that cannot obtain LetsEncrypt certificates.

For a local development setup, you may wish to export the self-signed certificate to other machines to that they can connect to your server over HTTPS, which you can do as follows:

The self-signed certificate was generated by make-ssl-cert, but its subject name must match the fully-qualified domain name (FQDN) that you will use from other machines to connect to the Debusine server. If hostname -f does not match the FQDN you will use from other machines, then you must first correct it:
Make the unqualified hostname be an alias for the FQDN in /etc/hosts. For example, you might change 127.0.1.1 debusine to read 127.0.1.1 debusine.incus debusine.
Regenerate the self-signed certificate:
$ sudo make-ssl-cert -f generate-default-snakeoil
Restart Nginx using the new certificate:
$ sudo systemctl restart nginx.service
The self-signed certificate is in /etc/ssl/certs/ssl-cert-snakeoil.pem on your Debusine server. On each machine from which you want to connect to the server:
Place a copy of the self-signed certificate in /usr/local/share/ca-certificates/{fqdn}.crt (replacing {fqdn} with the fully-qualified domain name of your Debusine server).
Update the system’s certificate collection:
$ sudo update-ca-certificates
Verify that Debusine’s welcome page loads, using curl https://{fqdn}/ from a machine where you installed a copy of the self-signed certificate.

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).