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 Creating a token for a Debusine Client explains how to create a token for a client.

1. Create the directory for the config.ini file:

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

2. Copy the example config.ini file to this directory:

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

3. Edit the config.ini file:

   $ editor "$HOME/.config/debusine/client/config.ini"
   

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

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

Submitting a work request

To submit a work request:

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

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

   $ 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
   

2. Submit the work request of type sbuild:

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

   The command will show an output such as:

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

3. Check the status of the work request:

   $ debusine work-request-status 5
   

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