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’ or Debian 11 ‘bullseye’ (using bullseye-backports).
$ 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. 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 debusineThe 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 alocal.py
file:$ sudo cp -i /etc/debusine/server/local.py.sample \ /etc/debusine/server/local.pyAnd 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 toproduction.py
, but this can be changed todevelopment.py
.Initialize the database:
$ sudo -u debusine-server debusine-admin migrateCommands can be issued to the server, for example:
$ sudo -u debusine-server debusine-admin list_tokensTo see the list of commands:
$ sudo -u debusine-server debusine-admin helpThe 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.netChange 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.netSearch 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-enabledWhen setting up a new server, the default Nginx server configuration may need to be deleted:
$ sudo rm /etc/nginx/sites-enabled/defaultRestart Nginx:
$ sudo systemctl restart nginxIf 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.pySet 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-serverVerify 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
userCollects 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 usingsystemctl list-timers
, disable it for the next boot viasystemctl disable debusine-server-monthly-cleanup.timer
or stop it nowsystemctl stop debusine-server-monthly-cleanup.timer
).