.. _setting-up-debusine-client:

==========================
Setting up debusine-client
==========================

Introduction
------------

The ``debusine-client`` package provides the command ``debusine``. This command
is used to submit work requests to the Debusine server and to look into the status
of the requests.

Initial setup
-------------

The ``debusine-client`` needs the Debusine server URL and an enabled token for the
server. The Debusine Server administrator can provide you with a token. The section
:ref:`Creating a token for a Debusine Client <creating-token-for-debusine-client>`
explains how to create a token for a client.


  #. Create the directory for the ``config.ini`` file:

     .. code-block:: console

       $ mkdir --parents "$HOME/.config/debusine/client"

  #. Copy the example ``config.ini`` file to this directory:

     .. code-block:: console

       $ cp /usr/share/doc/debusine-client/examples/config.ini "$HOME/.config/debusine/client/"

  #. Edit the ``config.ini`` file:

     .. code-block:: console

       $ editor "$HOME/.config/debusine/client/config.ini"
  
  #. Rename ``[server:localhost]`` to ``[server:server_name]`` and set
     ``default-server = server_name``. The Debusine client supports multiple
     servers, one of which is a default server. It is possible to specify to which server
     the Debusine client connects using the argument ``--server NAME``.


  #. Set the ``url`` and ``token``. The Debusine Server admin should create a token
     on the server for this client.

.. _submitting-a-work-request:
Submitting a work request
-------------------------

To submit a work request:

  #. Create a file with the work request, for example:

     .. code-block:: console

      $ cat > work-request-hello.debusine << END
      build_components:
      - any
      - all
      distribution: stable
      host_architecture: amd64
      input:
        source_package_url: https://deb.debian.org/debian/pool/main/h/hello/hello_2.10-2.dsc
      END

     It is possible to add sbuild options. For example, to add
     ``post-build-commands`` include the ``sbuild_options`` section:

     .. code-block:: console

      $ cat > work-request-hello.debusine << END
      build_components:
      - any
      - all
      distribution: stable
      host_architecture: amd64
      input:
        source_package_url: https://deb.debian.org/debian/pool/main/h/hello/hello_2.10-2.dsc
      sbuild_options:
      - --post-build-commands=/bin/cp %SBUILD_CHANGES "{changes_path}"
      END

  #. Submit the work request of type sbuild:

     .. code-block:: console

       $ debusine create-work-request sbuild < work-request-hello.debusine

     The command will show an output such as:

     .. code-block:: yaml

       result: success
       message: Work request registered on http://localhost/api with id 5.
       work_request_id: 5

  #. Check the status of the work request:

     .. code-block:: console

       $ debusine work-request-status 5

  #. If the status shows ``status: pending`` without a ``worker`` it might indicate
     that there is no ``debusine-worker`` available yet. At some point, the
     work request will have a ``worker`` assigned and then the status should be
     ``running``, then ``completed`` or ``aborted``.

     Once the status is ``completed``, the field ``result`` will be ``success``
     or ``failure``.


Output of the ``debusine`` command
----------------------------------
If the ``debusine`` command succeeds, it prints relevant information to the
standard output in YAML format.

If an error occurs, the error messages will be printed to the standard error.

Return values
-------------

Return values of the ``debusine`` command:

===============  ==================================================================================
  Return value    Meaning
===============  ==================================================================================
 0                Success
 1                Error: unhandled exception. Please report the error
 2                Error: wrong arguments and options
 3                Error: any other type of error such as connection to the server is not possible,

                  invalid configuration file, etc.
===============  ==================================================================================
