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:
  1. 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 .

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

  3. Initialize the database:

    $ sudo -u debusine-server debusine-admin migrate
    
  4. 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.

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

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.

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

  2. 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
    
  3. Restart Nginx:

    $ sudo systemctl restart nginx
    
  4. 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)

  5. Restart to apply the new settings:

    $ sudo systemctl restart debusine-server
    
  6. 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