The debusine-admin command

The debusine-admin command is the usual django-admin command of a Django project. But debusine adds many custom management commands that are documented on this page.

This command must be executed on the server while connected as the debusine-server user. For example, to run the command check:

$ sudo -u debusine-server debusine-admin check

For commands that are currently undocumented, you can still explore their features by using the --help command line option:

$ sudo -u debusine-server debusine-admin edit_worker_metadata --help

Command output

If a command is successful: nothing is printed and the return code is 0.

Managing workers

manage_worker

The command manage_worker has two actions: enable and disable.

Workers are disabled by default: they do not receive any tasks to run.

To enable a worker find the name list_workers command and then enable the worker using the manage_worker. To enable the worker worker-01:

sudo -u debusine-server debusine-admin manage_worker enable worker-01

To disable a worker: use disable instead of enable.

edit_worker_metadata

Debusine sysadmin can attach metadata to a worker. To edit the worker metadata for worker-01:

sudo -u debusine-server debusine-admin edit_worker_metadata worker-01

The worker metadata needs to be in YAML. The command edit_worker_metadata launches sensible-editor to edit the metadata.

list_workers

List workers with information:

$ sudo -u debusine-server debusine-admin list_workers
Name                                     Registered                        Connected                         Token                                                             Enabled
---------------------------------------  --------------------------------  --------------------------------  ----------------------------------------------------------------  ---------
debusine                                 2023-10-02T14:13:12.342630+00:00  2024-01-10T10:41:46.716838+00:00  34c9c6d7ae395323c2ec6050cf4513bbf1fa9947701a0d7ba402ceba2e702c2f  False
ansible                                  2023-12-20T15:03:36.008399+00:00  -                                 0d5cbfe1539b189e2108ffefe7458b7651a6a688ca408d9568886c883693a7fc  True

Number of workers: 2

If a worker is not connected at this time: the Connected column has -. If it’s connected: it has the time that connected.

Workers can be enabled or disabled using the command manage_worker.

Managing users

create_user

Users can be created using the create_user command. The password for the new user will be printed.

$ sudo -u debusine-server debusine-admin create_user john.doe john@example.org
m;Ag[2BcyItI..=M

A user can login on the website and then create tokens to be used by debusine client.

Tokens for a debusine user (to be used by debusine client) can also be created using the command create_token.

manage_user

Users can be managed using manage_user. To change the email of the john.doe user to johnd@example.org:

sudo -u debusine-server debusine-admin manage_user change-email john.doe johnd@example.org

changepassword

Change the password for a user. The password is asked interactively:

sudo -u debusine-server debusine-admin changepassword john.doe

create_super_user

Create a super user. Super users have access to the admin section of debusine-server (currently not used).

$ sudo -u debusine-server debusine-admin createsuperuser

The username is asked interactively.

list_users

List the users with their email and date_joined.

$ sudo -u debusine-server debusine-admin list_users

username                  email              date_joined
------------------------  ------------------ ---------------------------------
john.doe                  johnd@example.org   2024-01-10T14:10:52.667568+00:00

Number of users: 1

Manage workspaces

create_workspace

Artifacts belong to workspaces. To create a workspace:

$ sudo -u debusine-server debusine-admin create_workspace Debian

Workspaces are created Private by default (only registered users can access its resources) and without a default expiration delay. Use manage_workspace to change the permissions or expiry delay.

manage_workspace

Change a workspace. The command has the options:

  • --private: make the workspace private (only authenticated users can see the resources in it)

  • --public: non-logged users can see the resources of the workspace

  • --default-expiration-delay [DAYS]: set the default expiration delay for the artifacts that are created in this workspace.

To change the permissions of the workspace Debian to public:

$ sudo -u debusine-server debusine-admin manage_workspace Debian --public

list_workspaces

List the workspaces with information:

$ sudo -u debusine-server debusine-admin list_workspaces
Name    Public    Default Expiration Delay (days)    Default File Store      # Other File Stores
------  --------  ---------------------------------  --------------------  ---------------------
System  True      Never                              Default (Local)                           0
Debian  False     Never                              Default (Local)                           0

Number of workspaces: 2

Manage work requests

list_work_requests

List the work requests and its status. Similar information can be displayed using the web interface of debusine.

$ sudo -u debusine-server debusine-admin list_work_requests
id  worker                                   created_at                        started_at                        completed_at                      status     result
----  ---------------------------------------  --------------------------------  --------------------------------  --------------------------------  ---------  --------
1  debusine                                 2023-10-02T14:17:54.213857+00:00  2023-10-02T14:17:54.291425+00:00  2023-10-02T14:18:58.489656+00:00  completed  success
2  ansible-worker-2                         2023-10-06T10:04:06.731566+00:00  2023-10-06T10:04:06.806152+00:00  2023-10-06T10:05:07.050323+00:00  completed  success

Number of work requests: 2

Manage notification channels

create_notification_channel

Create a notification channel:

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

notification channels can be used when creating a work request.

Currently only the type email is implemented.

See Enable notifications for failed work requests for more information.

manage_notification_channel

To change the name of a notification channel from Debian to Debian-LTS:

$ sudo -u debusine-server debusine-admin manage_notification_channel change-name Debian Debian-LTS

To change the associated data to the notification channel:

$ sudo -u debusine-server debusine-admin manage_notification_channel change-data Debian-LTS << EOF
{
  "from": "admin@example.org",
  "to": ["new-to@example.org"]
}
EOF

list_notification_channels

List the notification channels with their information.

$ sudo -u debusine-server debusine-admin list_notification_channels

name        method    data
----------  --------  -----------------------------------------------------------
Debian-LTS  email     {'to': ['lts222@example.com'], 'from': 'admin@example.com'}

Number of notification channels: 1

delete_notification_channel

Deletes a notification channel.

$ sudo -u debusine-server debusine-admin delete_notification_channel Debian-LTS

Managing tokens

create_token

Create a token. Must be associated to a user. The token is printed to the stdout. Users can also create tokens using the web interface.

$ sudo -u debusine-server debusine-admin create_token john.doe
ed73404d2edd232bc20955a2316a16c41e9b0bf2c240d6aceb7bf0706cb6d78f
debian@debusine:~$

The tokens created by create_token are enabled by default.

In debusine, there can be tokens that are not associated to users. They are created when a debusine-worker registers to debusine-server.

manage_token

Current actions of manage_token are enable and disable. For example:

$ sudo -u debusine-server debusine-admin manage_token disable ed73404d2edd232bc20955a2316a16c41e9b0bf2c240d6aceb7bf0706cb6d78f

list_tokens

The command list_tokens lists all tokens by default. It is possible to filter tokens by the owner or the token itself, using the options --owner or --token, for example:

$ sudo -u debusine-server debusine-admin list_tokens --owner OWNER
$ sudo -u debusine-server debusine-admin list_tokens --token TOKEN

delete_tokens

Tokens can be removed using the delete_tokens command. By default, it asks for interactive confirmation unless --yes is used. See the options using:

$ sudo -u debusine-server debusine-admin delete_tokens --help

Administrative commands

delete_expired_artifacts

Delete expired artifacts if no other artifact depends on them.

$ sudo -u debusine-server debusine-admin delete_expired_artifacts

The debusine-server package installs a systemd timer to run this command daily.

monthly_cleanup

Report and fix inconsistencies in Debusine’s DB and storage.

$ sudo -u debusine-server debusine-admin monthly_cleanup

The debusine-server package installs a systemd timer to run this command monthly.