# 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 13 ‘trixie’.

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

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

> 2. 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`.

> 3. Commands can be issued to the server, for example:

>        $ sudo debusine-admin list_tokens

>    To see the list of commands:

>        $ sudo debusine-admin help

>    The Debusine specific commands are under the `[server]` section.

> 4. Configure a webserver (see below for details on how to use Nginx or another webserver with the default setup of debusine-server using gunicorn).

>    You can run `sudo 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 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
      list_notification_channels
      list_tokens
      list_users
      list_work_requests
      manage_notification_channel
      manage_user
      vacuum_storage
      worker

You can see the command specific help using `--help`, for example:

    $ sudo 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 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 make Debusine available on `/var/lib/debusine/server/debusine.sock`. There is also a ready-to-use Nginx virtual host pointing to the `debusine.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, 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)

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

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

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

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

>    2. Regenerate the self-signed certificate:

>           $ sudo make-ssl-cert -f generate-default-snakeoil

>    3. Restart Nginx using the new certificate:

>           $ sudo systemctl restart nginx.service

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

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

>    2. Update the system’s certificate collection:

>           $ sudo update-ca-certificates

> 3. Verify that Debusine’s welcome page loads, using `curl https://{fqdn}/` from a machine where you installed a copy of the self-signed certificate.

## Configuration with a different webserver

We recommend installing a HTTP proxy webserver in front of your ASGI server, to terminate HTTPS and serve the static traffic.

We don’t currently have sample configuration for any other webservers, but the critical things you need to do are:

1. Proxy the `Host` header, so the application knows what domain it is being served as.

2. Pass an `X-Forwarded-Proto` header declaring the client’s protocol (e.g. `https`), so the application knows when requests are secure.

## 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 debusine-admin collectstatic`)

- Provides ready-to-customize configuration files for Nginx/gunicorn (in `/etc/nginx/sites-available/debusine-server`)

- Installs a systemd service (`debusine-server.service`) that uses gunicorn to make the Debusine server available on `/var/lib/debusine/server/debusine.sock`

- Creates the directories `/var/log/debusine/server` and `/var/lib/debusine-server`

- Install a systemd timer unit to run daily `debusine-admin vacuum_storage`. (see it using `systemctl list-timers`, disable it for the next boot via `systemctl disable debusine-server-vacuum-storage.timer` or stop it now `systemctl stop debusine-server-vacuum-storage.timer`).