Project packaging

Introduction

The local builder can reproduce redpesk application packaging locally, using the same project and application definitions as the redpesk factory.

The examples use helloworld-binding as the application. For details about that sample itself, see its Build and installation documentation.

Security warning

Local packaging can only use unprotected project environments. Unprotecting an environment can expose project settings or secret definitions outside the redpesk factory. Use this workflow only with development environments, never with production environments containing sensitive configuration.

Before continuing:

• install and configure rp-cli;
• connect rp-cli to the local builder;
• create or select a project containing the application to package.

See Local builder installation and setup.

1. Unprotect the project environment

For security reasons, the local builder cannot initialize sources and application definitions from a protected environment.

You can unprotect a development environment from the WebUI, or with rp-cli:

rp-cli projects environments update my-awesome-project-1 default --unprotected true

Only users with the required project permissions can change this setting.

2. Initialize the local package

Initialize the application from its redpesk project definition:

rp-cli local package init helloworld-binding --project my-awesome-project-1

The command retrieves the application configuration and prepares the corresponding source and packaging workspaces in the local-builder directories.

Secrets handling

If the application configuration references secrets, rp-cli cannot retrieve their values automatically. Create a local secrets template:

rp-cli local secrets-init \
    --secrets-file ~/my_rp_builder_dir/my-secrets.json \
    my-awesome-project-1

Edit the generated JSON file and provide the required values. Keep this file outside gitpkgs and gitsources so that local-builder cleanup operations do not remove it.

Then initialize the package with the secrets file:

rp-cli local package init helloworld-binding \
    --project my-awesome-project-1 \
    --secrets-file ~/my_rp_builder_dir/my-secrets.json

To avoid repeating --secrets-file, set RP_SECRETS_FILE:

export RP_SECRETS_FILE=~/my_rp_builder_dir/my-secrets.json

Do not commit the secrets file to a source repository.

3. Modify sources or packaging

After initialization, the host-side local-builder workspace contains separate source and packaging directories.

For the default quickstart layout, the Hello World example is available under:

~/my_rp_builder_dir/gitsources/my-awesome-project-1/helloworld-binding/
~/my_rp_builder_dir/gitpkgs/my-awesome-project-1/helloworld-binding/

Modify application source code in gitsources and packaging metadata, such as the spec file, in gitpkgs.

4. Build the package locally

Select the target architecture with --arch.

For aarch64:

rp-cli local package build helloworld-binding \
    --project my-awesome-project-1 \
    --arch aarch64

For x86_64:

rp-cli local package build helloworld-binding \
    --project my-awesome-project-1 \
    --arch x86_64

The local builder prepares the mock environment, resolves the package build dependencies and executes the RPM build for the selected architecture.

5. Upload packaging changes

After validating a packaging change locally, upload the updated spec file with:

rp-cli local package commit helloworld-binding helloworld-binding.spec

Review the resulting change before using it in shared or production environments.

Troubleshooting inside the build environment

Open an interactive shell in the package build environment with:

rp-cli local package shell helloworld-binding \
    --project my-awesome-project-1 \
    --arch aarch64

Use this shell to inspect the RPM build tree, generated files, environment variables and installed build dependencies. If a package build has already run, its working files are available below the RPM build tree, for example under build/BUILD, build/SOURCES, build/SPECS and build/RPMS.

For the Hello World sample build procedure, use the commands documented in Build and installation.

Install an additional debugging package

The build environment does not have unrestricted network access. Ask rp-cli to install an additional package when preparing the build environment:

rp-cli local package build helloworld-binding \
    --project my-awesome-project-1 \
    --arch aarch64 \
    --install jq