Usage and examples

Global options management with rp-cli

Setting of global options is driven either by flags inside the command line, by environment variables, or using a config file knowing that the following priority order is used:

  1. Command line flag value (for example --serverurl https://community-app.redpesk.bzh)

  2. Exported environment variable RP_xxx. The environment variable named is formed by the prefix “RP” followed by the flag name, in uppercase. For example, the --serverurl flag corresponds to the RP_SERVERURL environment variable

  3. Else use the rp-cli-config.json configuration file, storing the wanted values for the flag. For example: {"serverurl": "https://community-app.redpesk.bzh"}

The default location for the configuration file is $HOME/.redpesk/rp-cli/rp-cli-config.json. This location can be changed either by using the --config flag or by exporting the RP_CONFIG environment variable.

Interactions with the redpesk infrastructure

Project identification in the redpesk infrastructure

In the redpesk infrastructure, a project can be identified by three different fields: ID, name or slug.

  • The ID of the project is an UUID generated by the redpesk infrastructure when the project is created. It is unique.
  • The name of the project is an identifier given by the user to a project. It is not unique and can contains special characters.
  • The slug of the project is either specified by the user or created by the redpesk infrastructure from the project name. It is not unique but cannot contain special characters.

To create the slug, the infrastructure processes the name given by the user. It gets rid of all special characters that are replaced by a dash. And the upper case letters are set to lower case ones.

# List the projects available for the user on redpesk infrastructure
> rp-cli projects list
ID                                     Slug                        Name                        Version        Type
b1a06375-0d28-4091-b9d6-4603cebe85dd   redpesk-ci                  Redpesk CI                  [Not set]      standard
77a6df2a-918a-4fff-a108-8c5f0ab4dc80   redpesk-industrial          Redpesk Industrial          [Not set]      standard
74c88f7a-3f5a-4072-bb29-2291fa8bc05a   redpesk-industrial-image    Redpesk Industrial Image    [Not set]      standard

While UUIDs are great to handle by bots, they are quite challenging for humans. This is why rp-cli handles both the ID and the slug when it comes to identifying projects on the command line.

# Get a project from its slug
> rp-cli projects get redpesk-industrial -v
ID:                      77a6df2a-918a-4fff-a108-8c5f0ab4dc80
Name:                    Redpesk Industrial
Slug:                    redpesk-industrial
Version:                 [Not set]
Type:                    standard
Supported Objects:       applications
Description:             It contains all the industrial applications
Distributions:           redpesk-lts-arz-1.1 [Mand]
Architectures:           x86_64 [Mand], aarch64 [Opt]
Creation time:           2022-04-21 10:30:41.362243 +0000 UTC
Update time:             2022-04-21 10:30:41.362243 +0000 UTC
Bookmarked:              false
Short release naming:    false

# Get a project from its ID
> rp-cli projects get 77a6df2a-918a-4fff-a108-8c5f0ab4dc80 -v
ID:                      77a6df2a-918a-4fff-a108-8c5f0ab4dc80
Name:                    Redpesk Industrial
Slug:                    redpesk-industrial
Version:                 [Not set]
Type:                    standard
Supported Objects:       applications
Description:             It contains all the industrial applications
Distributions:           redpesk-lts-arz-1.1 [Mand]
Architectures:           x86_64 [Mand], aarch64 [Opt]
Creation time:           2022-04-21 10:30:41.362243 +0000 UTC
Update time:             2022-04-21 10:30:41.362243 +0000 UTC
Bookmarked:              false
Short release naming:    false

N.B.: rp-cli can request the user to explicitly identify a project with its UUID if two projects have the same slug on the redpesk infrastructure.

Application identification in the redpesk infrastructure

Application identification on the redpesk infrastructure works in the same way as for projects. They have an ID, a slug and a name.

Additionally, applications have another field named package-name. This field is important because it is the identifier used to install the built package on targets (with dnf install command). The package name needs to be provided by the user during application creation, and needs to be unique within the project.

# Get the application named helloworld-binding
> rp-cli applications get helloworld-binding -v
ID:                   e9cb3f5f-271a-4ce2-b410-5f689ea68ab2
Name:                 Helloworld binding
Package Name:         helloworld-binding
Slug:                 helloworld-binding
Type:                 standard
Parent project:       redpesk-industrial
Description:          [Not set]
Source URL:           https://github.com/redpesk-samples/helloworld-binding.git
Source Revision:      master
External Specfile:    [Not set]
Distributions:        redpesk-lts-arz-1.1 [Mand]
Autotests:            OFF
Autoaudits:           OFF
Audits settings:      {"audit":null}
Creation time:        2022-04-21 10:30:46.496649 +0000 UTC
Update time:          2022-04-21 10:31:02.008922 +0000 UTC
Bookmarked:           false
Build type:           standard_build_cross
Services:

 - Name: download_sources
 - Parameters:
    download:      false
    force:         false

 - Name: excludearch
 - Parameters:
    arches:     []

 - Name: import_gitpkg
 - Parameters:
    ref: ""
    url: ""

 - Name: setverrel
 - Parameters:
    release:     true
    version:     true

Handling identifiers in scripts

In order to make scripting easy with rp-cli, it is possible to specify a slug or alias at project or application creation. It allows the script to interact with the created project or application using this slug, as it can be seen in the following example.

# Create a new project with the "my-new-project" alias
> rp-cli projects add -n "New project" -a my-new-project -d "This is a new project" --mandatory-distro redpesk-lts-arz-1.1 --optional-arch x86_64 --mandatory-arch aarch64
-- Project creation requested by user --
Checking that at least one architecture is set...   [OK]
Checking that at least one distribution is set...   [OK]
Creation of "New project" project...                [OK]

# Creation of an application "hello-iot-bzh" within the "my-new-project" project
> rp-cli applications add -n "Hello Iot.bzh" -a hello-iot-bzh --pkg-name helloworld-binding --project my-new-project --source-url https://github.com/redpesk-samples/helloworld-binding.git --specfile-sources conf.d/packaging/helloworld-binding.spec

-- Application creation requested by user --
Processing the distribution(s) settings...          [OK]
Creation of "Hello Iot.bzh" application...          [OK]
Wait for creation confirmation from the backend...  [OK]

# Start the build of the "hello-iot-bzh" application
> rp-cli applications build hello-iot-bzh -v
-- Application build requested by user --
Building the "hello-iot-bzh" application...

[..]

# Start the tests of the "hello-iot-bzh" application
> rp-cli applications test hello-iot-bzh -v
-- Application test requested by user --
Testing the "hello-iot-bzh" application on build 1012...

[..]

Other command examples

Here below one can find a few basic examples of rp-cli use, interacting with the redpesk infrastructure.

# Get the list of all the available architectures in the redpesk instance
rp-cli misc arch

# Get the list of all the available distributions in the redpesk instance
rp-cli misc distributions

# Get the list of all the available projects in the redpesk instance (verbose option)
rp-cli projects list -v

# Get the list of all the available applications in the redpesk instance (non-verbose option)
rp-cli applications list

# Creation of a new project called "IOT Project", without waiting for the acknowledgement events
# Note: the project slug, being based on the project name, will end up being "iot-project"
rp-cli projects add --nonblocking -n "IOT Project" --mandatory-arch x86_64 --optional-arch aarch64 --mandatory-distro redpesk-lts-arz-1.1

# Creation of a new application named "Helloworld binding" within the project whose slug is "iot-project"
rp-cli applications add --name "Helloworld binding" -d "This is my beautiful app" --pkg-name "helloworld-binding" --source-rev "master" --source-url "https://github.com/redpesk-samples/helloworld-binding.git" -p "iot-project"

# Upload a specfile for the application with the slug "helloworld-binding"
rp-cli applications upload helloworld-binding /home/me/iot-app.spec /home/me/iot_example.tar.bz2 /home/me/bl31_atf.bin

# Get the list of all the available applications contained in the project whose slug is "iot-project"
rp-cli applications list -p iot-project

# Start a new build for the application "helloworld-binding", verbose option
rp-cli applications build helloworld-binding

# Start a new test for the application "helloworld-binding", on the latest build, verbose option
rp-cli applications test helloworld-binding -v

# Retrieve the builds list for the application "helloworld-binding"
rp-cli applications builds list helloworld-binding

# Start a new test on the build #1068 (buildsID can be seen with 'rp-cli applications builds list')
rp-cli applications test 1068

# Get the list of all the tests for the application "helloworld-binding"
rp-cli applications tests list helloworld-binding

# Get the list of public teams in the redpesk instance, with verbose option
rp-cli teams list --verbose

# Download the logs of the latest build of the application "helloworld-binding" in the directory "/tmp"
rp-cli applications builds logs helloworld-binding -p iot-project -d /tmp

# Download the logs of the latest test of the application "helloworld-binding",
# from the project "my-project" in the current directory
rp-cli applications tests logs helloworld-binding -p iot-project --directory /tmp/

Interactions with the local builder

As it has been said in the introduction, rp-cli now allows to package locally your application before doing it on the redpesk infrastructure. Therefore, it permits to have a quick iteration cycle time while packaging. It also allows to build locally your own custom redpesk image.

In order to do that, the local builder needs to be installed in your host. Please refer to the local builder’s installation chapter for more information about it.

Moreover, rp-cli needs to have the correct local builder’s parameters set. If the configuration have not been done yet, please refer to the rp-cli local builder configuration.

Build initialization

Before building an application locally, the user needs to initialize the build environment. This initialization is pretty straight forward, just call the rp-cli local package init command with the application slug. The project flag may be needed if the user has access to several applications with the same slug.

Several examples of initialization can be found here below, corresponding to different cases.

# Simple initialization for an application 
> rp-cli local package init simple-helloworld

-- Package initialization requested by user --

Retrieve application details...		[OK]
Check local-builder configuration...	[OK]

"gitsources/" directory used: 	/home/armand/my_rp_builder_dir/gitsources
"gitpkgs/" directory used: 	    /home/armand/my_rp_builder_dir/gitpkgs

Retrieving package configuration for "simple-helloworld"	[OK]
Setting up the local-builder...
Create directories if needed...				              [OK]
Check 'gitpkg' repository status...			            [OK]
Fetch the 'gitpkg' repository from branch 'main'...	[OK]
Fetch local-builder configuration...			          [OK]
Cloning the package sources...

LOCAL-BUILDER LOGS >>>
Using config file:/etc/rpkg/iotpkg.conf
[DEBUG][redpesk_utils][parameter:template:220] METADATA | 1.1.0
[DEBUG][git.cmd][cmd:execute:857] Popen(['git', 'ls-remote', '--symref', 'https://github.com/redpesk-samples/simple-helloworld.git', 'HEAD'], cwd=/home/devel/gitpkgs/another-simple-project/simple-helloworld, universal_newlines=False, shell=None, istream=None)
[INFO][redpesk_utils][gitsource:_set_commit_checkout:108] Will try to checkout to master (commit_checkout)
[DEBUG][git.cmd][cmd:execute:857] Popen(['git', 'ls-remote', '--heads', 'https://github.com/redpesk-samples/simple-helloworld.git', 'master'], cwd=/home/devel/gitpkgs/another-simple-project/simple-helloworld, universal_newlines=False, shell=None, istream=None)
[INFO][redpesk_utils][gitsource:_set_ref_type:410] Commit checkout master is set as a RefType.BRANCH ref
[DEBUG][redpesk_utils][gitsource:gitsource:733] Remove ../../../gitsources/another-simple-project/simple-helloworld
[INFO][redpesk_utils][gitsource:_shallow_clone:143] Trying shallow clone source from https://github.com/redpesk-samples/simple-helloworld.git:master into ../../../gitsources/another-simple-project/simple-helloworld
[DEBUG][git.cmd][cmd:execute:857] Popen(['git', 'clone', '-v', '--branch=master', '--depth=1', '--single-branch', 'https://github.com/redpesk-samples/simple-helloworld.git', '../../../gitsources/another-simple-project/simple-helloworld'], cwd=/home/devel/gitpkgs/another-simple-project/simple-helloworld, universal_newlines=True, shell=None, istream=None)
[DEBUG][git.repo.base][base:_clone:1075] Cmd(['git', 'clone', '-v', '--branch=master', '--depth=1', '--single-branch', 'https://github.com/redpesk-samples/simple-helloworld.git', '../../../gitsources/another-simple-project/simple-helloworld'])'s unused stdout: 
[INFO][redpesk_utils][gitsource:_shallow_clone:148] Successfull shallow cloned.
[DEBUG][git.cmd][cmd:execute:857] Popen(['git', 'cat-file', '--batch-check], cwd=/home/devel/gitsources/another-simple-project/simple-helloworld, universal_newlines=False, shell=None, istream=<valid stream>)
<<< LOCAL-BUILDER LOGS

# Initialization when the user want to build locally a different branch than the current active one
> rp-cli local package init simple-helloworld --project simple-project --branch devel

Build the application

Once the initialization is correctly done, the application can be built with rp-cli. An architecture needs to be specified (x86_64 or aarch64), using the --arch flag . The default architecture value being aarch64. If the project supports several distributions, a distribution needs to be specified using the --distro flag.

Here below, several examples of rp-cli local package build commands.

# Build for x86_64 architecture, on the only distribution supported for the application named 'simple-helloworld'
rp-cli local package build simple-helloworld --arch x86_64

# Build for aarch64 architecture, on the 'redpesk-lts-batz-2.0-update' distribution
rp-cli local package build simple-helloworld --arch aarch64 --distro redpesk-lts-batz-2.0-update

Other ‘local package’ subcommands

Here below, the list of all the ‘local package’ subcommands supported by rp-cli with their description.

rp-cli local package          -- Packaging sub-command group
rp-cli local package build    -- Build locally an application
rp-cli local package clean    -- Delete all the directories created for local building
rp-cli local package commit   -- Upload files that have been modified/added/deleted in your working directory, to the remote gitpkg in the redpesk factory
rp-cli local package fetch    -- Fetch content from the redpesk factory, create or update a local working directory
rp-cli local package init     -- Initialization needed by the local builder to package
rp-cli local package metadata -- Set application metadata value
rp-cli local package service  -- Set application service value
rp-cli local package shell    -- Allow to get a shell inside the mock used to build
rp-cli local package status   -- Show the status of files in a local working directory