.. _debusine-admin-cli:

==========================
The debusine-admin command
==========================

The ``debusine-admin`` command is the usual `django-admin
<https://docs.djangoproject.com/en/3.2/ref/django-admin/>`_ command
of a Django project. But debusine adds many `custom management commands
<https://docs.djangoproject.com/en/3.2/howto/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``:

.. code-block:: console

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

.. code-block:: console

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

.. code-block:: console

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

.. code-block:: console

  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:

.. code-block:: console

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

.. code-block:: console

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

.. code-block:: console

  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:

.. code-block:: console

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

.. code-block:: console

  $ sudo -u debusine-server debusine-admin createsuperuser

The username is asked interactively.

``list_users``
~~~~~~~~~~~~~~

List the users with their `email` and `date_joined`.

.. code-block:: console

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

.. code-block:: console

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

.. code-block:: console

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

``list_workspaces``
~~~~~~~~~~~~~~~~~~~

List the workspaces with information:

.. code-block:: console

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

.. code-block:: console

  $ 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

.. _debusine-admin-notification-channels:

Manage notification channels
----------------------------

``create_notification_channel``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Create a notification channel:

.. code-block:: console

  $ 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 :ref:`configure-notifications` for more information.

``manage_notification_channel``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

.. code-block:: console

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

To change the associated data to the notification channel:

.. code-block:: console

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

.. code-block:: console

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

.. code-block:: console

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

.. code-block:: console

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

.. code-block:: console

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

.. code-block:: console

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

.. code-block:: console

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

Administrative commands
-----------------------

.. _command-delete-expired-artifacts:

``delete_expired_artifacts``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Delete expired artifacts if no other artifact depends on them.

.. code-block:: console

  $ sudo -u debusine-server debusine-admin delete_expired_artifacts

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

.. _command-monthly-cleanup:

``monthly_cleanup``
~~~~~~~~~~~~~~~~~~~

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

.. code-block::

  $ sudo -u debusine-server debusine-admin monthly_cleanup

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