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 show-work-request 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.

Creating an artifact

To create an artifact for the category Test uploading FILE1 and FILE2:

$ debusine create-artifact Test --workspace System --upload FILE1 FILE2
result: success
message: New artifact created in http://localhost:8011/api in workspace System with id 61.
artifact_id: 61
files_to_upload: 2

The artifact is creating and the file are uploaded automatically.

Check the documentation for the create-artifact regarding uploading multiple files, files relative to a directory, etc. using:

$ debusine create-artifact --help

The artifact can be downloaded via:

$ debusine download-artifact ARTIFACT_ID

Creating an sbuild work-request using an artifact

In the example above sbuild downloaded the .dsc file.

In this section debusine will download the artifact and sbuild will use the .dsc (and other required files) from the artifact.

1. Prepare a directory with the relevant files

   $ mkdir temp_directory/
   $ cd temp_directory/
   $ wget http://deb.debian.org/debian/pool/main/h/hello/hello_2.10-2.dsc \
          http://deb.debian.org/debian/pool/main/h/hello/hello_2.10.orig.tar.gz \
          http://deb.debian.org/debian/pool/main/h/hello/hello_2.10-2.debian.tar.xz
   

2. Create the artifact

   $ debusine create-artifact Test --workspace System --upload *
   result: success
   message: New artifact created in http://localhost:8011/api in workspace System with id 62.
   artifact_id: 62
   files_to_upload: 3
   

3. Create the file indicating the artifact_id that is going to be used:

   $ cat > work-request-hello.debusine << END
   build_components:
   - any
   - all
   distribution: stable
   host_architecture: amd64
   input:
     artifact_id: 62
   END
   

4. Create the work-request

   $ debusine create-work-request sbuild < work-request-hello.debusine
   result: success
   message: Work request registered on http://localhost:8011/api with id 53.
   work_request_id: 53
   

5. Check the status:

   $ debusine show-work-request 53
   

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.