Usage and examples

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
0aad1d06-e2cd-4b65-b3d4-663c9adcdb38     banano-project           Banano Project
73d3237b-304b-45c8-9b7e-c86aa7d58d0a     best-project             Best Project

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 banano-project -v
ID:               0aad1d06-e2cd-4b65-b3d4-663c9adcdb38
Name:             Banano Project
Slug:             banano-project
Description:      [Not set]
Distributions:    redpesk-devel-33 [Mand]
Architectures:    x86_64 [Mand], aarch64 [Opt]
Creation time:    2020-12-15 14:24:27.832661 +0000 UTC
Update time:      2020-12-15 14:24:27.832663 +0000 UTC
Bookmarked:       false

# Get a project from its ID
> rp-cli projects get 0aad1d06-e2cd-4b65-b3d4-663c9adcdb38 -v
ID:               0aad1d06-e2cd-4b65-b3d4-663c9adcdb38
Name:             Banano Project
Slug:             banano-project
Description:      [Not set]
Distributions:    redpesk-devel-33 [Mand]
Architectures:    x86_64 [Mand], aarch64 [Opt]
Creation time:    2020-12-15 14:24:27.832661 +0000 UTC
Update time:      2020-12-15 14:24:27.832663 +0000 UTC
Bookmarked:       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:                      2aab66bd-f265-465f-9b74-11d67c11c2f9
Name:                    Helloworld binding
Package Name:            helloworld-binding
Slug:                    helloworld-binding
Parent project:          banano-project
Description:             [Not set]
Source URL:              http://git.ovh.iot/redpesk/redpesk-samples/helloworld-binding.git
Source Revision:         master-next
External Specfile URL:   [Not set]
Distributions:           redpesk-devel-33 [Mand]
Autotests:               OFF
Creation time:           2020-12-15 16:31:31.149495 +0000 UTC
Update time:             2020-12-16 14:15:46.76001 +0000 UTC
Bookmarked:              false

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-devel-33 --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 --
No build ID specified, get the latest one...		1012
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-devel-28

# Creation of a new application named "IOT Application" within the project whose slug is "iot-project"
rp-cli applications add --name "IOT Application" -d "This is my beautiful app" --pkg-name "agl-service-helloworld" --source-rev "master-next" --source-url "http://git.ovh.iot/redpesk/redpesk-samples/agl-service-helloworld.git" -p "iot-project"

# Upload a specfile for the application with the slug "iot-application"
rp-cli applications upload iot-application --file-path /home/me/iot-app.spec

# 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 "iot-application", verbose option
rp-cli applications build iot-application -v

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

# Start a new test for the application "iot-application", on the build #1068
rp-cli applications test iot-application --build 1068

# Get the list of all the builds for the application "iot-application", with verbose option
rp-cli applications builds-list iot-application -v

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

# 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 "redtest-helloworld-api" in the directory "/tmp"
rp-cli applications build-logs redtest-helloworld-api -d /tmp

# Download the logs of the latest test of the application "redtest-helloworld-api",
# from the project "my-project" in the current directory
rp-cli applications test-logs redtest-helloworld-api -p my-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.

In order to package an application locally, an initialization step is necessary. Of course, the local builder’s connection configuration is necessary to package locally.

Moreover, the local builder and your host needs to share directories, especially two of them: gitsources/ and gitpkgs/. You must have chosen these directories on your host during the local builder installation. You can specify the paths to these directories each time you run a rp-cli local package command using the --pkgsdir and --sourcesdir flags but it is not the most graceful way. A better way is to write these values directly inside the rp-cli’s configuration file (located in $HOME/.redpesk/rp-cli/rp-cli-config.json):

{
  "serveralias": "default",
  "sourcesdir": "/home/devel/sandbox/gitsources",
  "pkgsdir": "/home/devel/sandbox/gitpkgs"
}

Packaging initialization

Before packaging an application, the user needs to specify some parameters to rp-cli. If the application already exists in the redpesk infrastructure, less parameters are needed. However, rp-cli always needs that at least the project, that will contain the application, exists.

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

# Initialization for an application already existing in the redpesk infrastructure
> rp-cli local package init redtest-helloworld-api --project banano-project

-- Package initialization requested by user --

Checking application details...		[OK]
Checking packaging directories...	[OK]

"gitsources/" directory used: 	/home/devel/sandbox/gitsources
"gitpkgs/" directory used: 	/home/devel/sandbox/gitpkgs

Retrieving package configuration for "redtest-helloworld-api"	[OK]
Setting up the local-builder...
Cloning the package sources...

CLONE LOGS >>>
Cloning into 'redtest-helloworld-api'...
remote: Enumerating objects: 58, done.        
remote: Counting objects: 100% (58/58), done.        
remote: Compressing objects: 100% (51/51), done.        
remote: Total 58 (delta 13), reused 0 (delta 0), pack-reused 0        
Receiving objects: 100% (58/58), 15.17 KiB | 1.90 MiB/s, done.
Resolving deltas: 100% (13/13), done.
<<< CLONE LOGS

Working out the spec file...
Creation of the sources archives inside local builder...

ARCHIVE LOGS >>>
Archive redtest-helloworld-api-1.0.tar.bz2 not found within /home/devel/gitpkgs/redtest-helloworld-api, force generation...
Will try to checkout to master (commit_checkout)
Fetching repo from /home/devel/gitsources/redtest-helloworld-api
Commit checkout master is set as a RefType.BRANCH ref
Successful checkout to master
Current commit is 97310554a3cbb1db0dc8dac509637b6b0aa77986
Version is 1.0
Making archive ...
redtest-helloworld-api-1.0.tar.bz2
<<< ARCHIVE LOGS

The spec file 'redtest-helloworld-api.spec' has been copied to '/home/devel/sandbox/gitpkgs/redtest-helloworld-api'
Please modify '/home/devel/sandbox/gitpkgs/redtest-helloworld-api/redtest-helloworld-api.spec' while working on packaging, only this specfile is used when running 'rp-cli local package run'

# Initialization for an application that does not exist in the redpesk infrastructure
# In this case, the sources are downloaded from the given GIT repository with the given revision
# The spec file is local
> rp-cli local package init redtest-helloworld-api --project best-project --source-url http://git.ovh.iot/redpesk/redpesk-samples/redtest-helloworld-api.git --repo-rev master-next --spec-path conf.d/packaging/rpm/redtest-helloworld-api.spec

# Initialization for an application that does not exist in the redpesk infrastructure
# In this case, the package sources (archive + specfile) are downloaded from the given GIT repository on the default rev (master)
> rp-cli local package init helloworld-binding --project best-project --package-url http://iotbzh-git-dev01.lorient.iot/iotbzh-runtime-dev01.lorient.iot/redpesk-samples/helloworld-binding.git

Packaging runs

Once the initialization is correctly done, the application can be packaged with rp-cli. A target needs to be specified (x86_64 or aarch64), the default value being aarch64. The project slug needs to be provided as well.

Several other flags allow to debug interactively the application packaging. For example, the use of --no-clean-after followed, on the next iteration, by the use of --shell allows to enter inside the mock used to build your package and to discover the build environment thanks to a shell. Other useful flags are available for debugging. To learn more, simply run rp-cli local package run -h in your terminal!

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

# Request to recreate the archive and then package the 'redtest-helloworld-api' for x86_64 architecture
> rp-cli local package run redtest-helloworld-api --target x86_64 --project banano-project --regen-archive

# Request to package the 'redpesk-lad' application without cleaning the mock after (allows to debug porential problems)
# The package will be done for aarch64 architecture
> rp-cli local package run redpesk-lad --project banano-project --no-clean-after

Iotpkg wrapping

iotpkg is a powerful tool running inside the local builder. rp-cli allows to use it outside the container. In order to do that, be sure to have the pkgsdir value set inside the configuration file.

Then, go inside the “gitpkgs/” directory (or a subdirectory of it) on your host and run your iotpkg command (prefixed by rp-cli).

For example, if the rp-cli configuration file looks like that:

{
  "serveralias": "default",
  "pkgsdir": "~/gitpkgs",
  "sourcesdir": "~/gitsources"
}

The command lines you need to run are:

$ cd ~/gitpkgs/helloworld-binding/
$ rp-cli iotpkg archive --path-source https://github.com/redpesk-samples/helloworld-binding.git
Will try to checkout to 229112d (commit_checkout)
Commit checkout 229112d is set as a RefType.SHA ref
Trying shallow clone source from https://github.com/redpesk-samples/helloworld-binding.git:master into /home/devel/gitpkgs/helloworld-binding/gitsource
Successfull shallow cloned.
Fetching with depth 11
Successful checkout to 229112d
Set version tag to 0.7.0+20210326+4+g229112d
Making archive ...
helloworld-binding-0.7.0+20210326+4+g229112d.tar.gz