FAQ:Add Software to a Provider-Managed Appliance

From rPath Wiki

Answer: This FAQ page describes the process for adding packages to an appliance with an emphasis on the package group structure comprising the appliance. This information will be useful to those who are building or maintaining a provider-managed appliance.

This page was composed for rBuilder 2.0.0. Recommended actions may vary in later versions of rBuilder.

What Makes an Appliance Provider-Managed?

A provider-managed appliance is comprised of a master group of packages which define the appliance. Each of these packages are added to the master group with the group recipe command, r.add, and the byDefault argument to r.add is set to True for each package specified in the group recipe.

In addition to the manner in which packages are added, a provider-managed appliance must use Conary's migrate command to update packages by migrating the master group to a new version. If the appliance uses the rPath Appliance Agent (rAA) to manage updates, the rAA configuration element updatetroves.migrate must be set to True in the rAA custom configuration file (/etc/raa/custom.cfg).

By configuring an appliance in this way, any packages that have been added to the appliance outside of the manner detailed above (by the appliance's end-user, for example) will be automatically removed during migration to a new version of the group defining the appliance.

If you define the appliance in any manner differing from the points above, then you will be defining a user-extensible appliance. As the name implies, packages can be added or removed from a user-extensible appliance by any individual with root-level access to the appliance, and those modifications will be preserved.

Adding Packages to an Appliance Group Recipe

The following sections describe adding additional packages to your appliance's group recipe to make the software available when the appliance is installed or updated.

What You Need

Before you can add packages to an appliance's group recipe, you should have the following:

• A Conary based system
• Commit access to the appliance's repository; if the appliance project is hosted on an rBuilder repository, you must have an account on the rBuilder hosting the project, and that account must have developer privileges for the appliance project.
• An environment for packaging software for the appliance project with Conary. Information for configuring this environment is available in the New Package Tutorial. Be sure to use the Conary packaging best practice of defining a configuration context for your project.

Check Out the Group

After you setup your packaging environment, the next step is to check out the group you wish to modify. You can skip this step and proceed with editing the group recipe if you already have your group checked out.

[user@localhost ~]$ cd conary
[user@localhost conary]$ cvc co <appliance-group>=<appliance-label>

The <appliance-group> is the master group of packages that your appliance is built on. A common name for this group is group-dist. The <appliance-label> specifies the repository and branch location of your appliance's master group.

Edit the Group Recipe

Now, you can use your preferred editor to edit the group recipe to include the additional package. Change into the package directory, and edit the package recipe:

[user@localhost conary]$ cd <appliance-group>
[user@localhost <appliance-group>]$ vim <appliance-group>.recipe

The recipe is a set of instructions describing how to assemble the various packages which comprise your appliance into a complete product. To reference your new package in the master group recipe, add an r.add line to the end of the recipe's setup function:

 
    def setup(r):
    r.setLabelPath('conary.rpath.com@rpl:devel','contrib.rpath.org@rpl:devel')
    ...
    r.add('<package>')
    ...

If the package being added comes from a non-standard label, you should add the label to the r.setLabelPath line if one is present in the recipe, or add the r.setLabelPath line to the group recipe so that it resembles the following:

 
    r.setLabelPath('<yourproject>.rpath.org@<branch>:<label>')

In addition to modifying <yourproject> to reflect the actual name of your project, change the <branch> and <label> in the example above to your project's actual branch and label names (for example, rpl:devel).

Save the recipe and exit from the editor.

Cook and Commit the Group Recipe

First, you should cook the recipe locally to ensure that the recipe does not contain errors:

[user@localhost <appliance-group>]$ cvc cook <appliance-group>.recipe

This command will process the recipe file and produce a Conary changeset file (.ccs) that describes all the changes which would be made to install the group. If the changeset file was created successfully, then proceed to committing the recipe to your project's repository:

[user@localhost <appliance-group>]$ cvc commit --message "Commit message here"

The commit message should describe what changes you made (in this case, what package was added) for the benefit of anyone looking at the history of your appliance.

Cook the group, so that the cooked changeset will be committed directly to the repository, making the updated group ready for use:

[user@localhost <appliance-group>]$ cvc cook <appliance-group>=<appliance-label>

If all was successful, your appliance should now include the newly-added package in subsequent builds and releases.

Testing the new Group Package

The next time you make a build or release of your appliance, the package added to your appliance's master group will be included in the appliance build or release images. If you want to test the new group without making a release, you can migrate an existing appliance to the new version using rAA.

This will update the appliance's current group of packages to match the group you just cooked and committed.

Updating to the new Group Package

Users of your appliance who have configured rAA for periodic updates should either automatically receive the updated group, or be informed that it is available for installation by the rPath Appliance Platform System Updates feature.