Skip to content

Latest commit

 

History

History
318 lines (257 loc) · 13.7 KB

chapter-yum.asciidoc

File metadata and controls

318 lines (257 loc) · 13.7 KB

RPM Packages and YUM Repositories

{inall}

Introduction

RPM packages and the RPM package manager solution yum are used as the default application package manager on Linux based operating systems such as Red Hat, CentOS, Fedora, Oracle Linux, SUSE, openSUSE, Scientific Linux and others.

The yum repository support of {pro} and {oss} allows you to expose RPM packages hosted in a Maven repository in the yum repository format. It generates the yum metadata, so that systems with yum support can use the repository manager as a software package repository.

This enables a build and deployment pipeline for Java or other JVM-based applications via Maven repositories to Linux computers. E.g., a Java Enterprise Archive (EAR) or Web Archive (WAR) or some other application is deployed to a Maven repository. The deployment is performed by a CI server build using Maven or other build systems or as a manually run deployment. Once the repository manager hosts the application RPM package, it can be retrieved via yum for installation and updates on testing and production systems. The metadata of the RPM package can additionally trigger installation of other required packages including e.g. a Java runtime or an application server.

Installation and Requirements

Yum support is bundled with {pro} and {oss} and no further installation steps are required. It relies on the commands createrepo and mergerepo to be installed on the operating system running the repository manager server and to be available on the path. Documentation about these commands can be found on the createrepo website. Typically createrepo is installed on RPM-based Linux distributions and as such they are suitable to run the repository manager with yum support. If desired the path to the commands can be configured in the user interface.

If your RPM-based system does not have this command you can install it by running

yum install createrepo

with a sufficiently privileged user.

Configuration

Yum related configuration is done with the 'Capabilites' management documented in [capabilities].

The capability 'Yum: Configuration' allows you to enable or disable yum support. It can only be enabled successfully, if the 'createrepo' and the 'mergerepo' commands can be found by the repository manager. By default it will look for them on the path. The configuration settings 'Path of "createrepo"' and 'Path of "mergerepo"' allow you to alternatively configure a specific absolute path.

The parameter 'Max number of parallel threads' defaults to ten and defines how many threads can be used to manage the yum repositories with the 'createrepo' and the 'mergerepo' commands.

You need to ensure that this capability is enabled, before proceeding with your repository specific configuration. The 'Status' tab of the capability displays the detected versions for createrepo and mergerepo and details any problems as applicable.

Configure Hosted Yum Repositories

To expose a Maven repository like 'Releases' via yum, press the 'New' button in the capabilities configuration tab and select 'Yum: Generate Metadata' from the 'Type' drop down in the dialog displayed in Yum Configuration for the Hosted 'Releases' Repository.

yum hosted
Figure 1. Yum Configuration for the Hosted 'Releases' Repository

The 'Repository' drop down allows you to select the hosted Maven repository. Release as well as snapshot policy repositories can be configured. Once configured, any RPM package added to the hosted Maven repository is available via yum. The same URL of the repository used for Maven based access e.g., http://localhost:8081/nexus/content/repositories/releases and displayed in the repository administration area list, can be used as the URL for a yum repository in the yum configuration.

The yum integration supports versioned views on a repository. The URL http://localhost:8081/nexus/service/local/yum/repos/releases/1.2.3/ exposes a yum repository with all packages with version 1.2.3 in the releases repository. A custom repodata folder is available at the context.

The 'Aliases' field can be used to define alternative access paths to specific versions. For example, you can configure alias values of

production=1.2,testing=2.0

These values would in turn expose the version 1.2 under a URL like http://localhost:8081/nexus/service/local/yum/repos/releases/production/ and the version 2.0 at http://localhost:8081/nexus/service/local/yum/repos/releases/testing/. Using these URLs in the yum configuration on the target servers as a static URL enables upgrades to new versions by simply changing the alias e.g. to production=1.3 and running a yum update command on the target server.

Besides maintaining the aliases in the capability administration, it is possible to create or update an alias in the command line:

curl -d "1.0" --header "Content-Type: text/plain" http://localhost:8081/nexus/service/local/yum/alias/releases/development/

Usage of the alias-based URL is done via the normal yum configuration e.g. with a file /etc/yum.repos.d/nexus-production.repo and the following content:

[nexus-production]
name=Production Repository
baseurl=http://localhost:8081/nexus/service/local/yum/repos/releases/production/
enabled=1
protect=0
gpgcheck=0
metadata_expire=30s
autorefresh=1
type=rpm-md
Promote RPM through Stages

By deploying new versions and switching alias associations to the versions, a controlled roll out of new versions of RPM archives to target servers can be achieved.

The configuration options 'Process deletes' and 'Delete process delay' can be used to enable updates to the yum metadata, following delete operations of rpm packages in the Maven repository.

The 'Yum groups definition file' configuration allows you to configure a path to a package groups configuration file. This file is typically named comps.xml and can be used to define a group of RPM packages. The groups can then be managed with commands such as yum grouplist, yum groupinstall and yum groupremove.

Once the capability is saved, the 'Status' tab displays an example yum configuration for accessing the repository. Each RPM deployed to the repository causes the repository manager to update the yum metadata immediately.

The metadata used by yum is available in the repodata context e.g., at .../nexus/content/repositories/releases/repodata, in the following files. Apart from the repomd.xml file, the files are prepended with a unique hash value as part of the name to avoid caching issues:

repomd.xml

This XML file contains information about the other metadata files.

hash-primary.xml.gz

This zipped XML file describes the primary metadata of each RPM archive in the repository.

hash-filelists.xml.gz

This zipped XML file describes all the files contained within each RPM archive.

hash-other.xml.gz

This zipped XML file contains further, miscellaneous information regarding each RPM archive.

Proxying Repositories

The yum integration is able to proxy yum-enabled Maven repositories from remote {nxrm} servers. The metadata in these repositories contains absolute URLs, which will cause yum to use these URLs. The capability 'Yum: Proxy Metadata' can be configured on such a proxy repository. It will cause the URLs in the metadata to be rewritten and corrected for the current repository manager.

This allows the proxy repositories to be part of a repository group and expose the correct yum metadata via the merged metadata creation on the group.

Configure Repository Group for yum

To expose a Maven repository group to yum, simply add a new capability with the type 'Yum: Merge Metadata' and select the repository group in the 'Group' drop down. Yum Configuration for the Hosted 'Releases' Repository shows the 'Settings' tab for the 'Public Repositories' configured for yum.

yum group
Figure 2. Yum Configuration for the Hosted 'Releases' Repository

This configuration causes the repository manager to merge the yum metadata of all repositories in the repository group. Metadata generation has to be configured for the individual repositories desired to be exposed as part of the group. The URL of the repository group, can now be used as the URL for a yum repository in the yum configuration, since the same metadata files are being maintained and exposed via the repodata context like in a hosted repository.

Scheduled Tasks

The yum support includes a scheduled task called 'Yum: Generate Metadata' that can be run to generate yum metadata with createrepo for a specific repository.

Typically this task does not need to be run, however it can be useful when RPM files already exist in a repository or are deployed in some external mode that requires a manually triggered update of the metadata.

The 'Optional Output Directory' parameter can be used to get the metadata created in a different folder from the default repo-data in repository root.

The parameter 'Single RPM per directory' is activated by default and causes the task to take only one RPM file per directory in the Maven repository into account when creating the yum metadata.

The 'Full Rebuild' parameter can be activated to force the repository manager to traverse all directories in the repository in order to find the RPM files that need to taken into account for the metadata creation. This option is off by default and causes the repository manager to take the existing metadata cache as a basis for the update.

Example Usages

The component upload to a hosted repository allows you to publish any RPM file to a Maven repository and subsequently expose it via the yum integration. This is a basic use case, that can be used to e.g., exposed third-party supplied RPM archives. The more advanced setup involves a Maven project that creates the RPM as detailed in this section.

The RPM Maven Plugin can be used to create an RPM package of a Java application and attach it as a secondary built component with the attached-rpm goal. An example plugin configuration for a war project can be found in [yum-rpm-pom].

If your project includes a distributionManagement for the releases repository, a build with mvn clean deploy, causes the war as well as the rpm file to be uploaded to the repository. With yum configured for the releases repository , the RPM package can be consumed by any server configured to access the repository with yum.

Maven pom.xml snippet for configuring and attaching an RPM

<build>
  <plugins>
    <plugin>
      <groupId>org.codehaus.mojo</groupId>
      <artifactId>rpm-maven-plugin</artifactId>
      <version>2.1</version>
      <executions>
        <execution>
          <id>build-rpm</id>
          <goals>
            <goal>attached-rpm</goal>
           </goals>
         </execution>
       </executions>
       <configuration>
         <group>Applications/Internet</group>
         <copyright>EPL</copyright>
         <requires>
           <require>tomcat8</require>
         </requires>
         <mappings>
           <mapping>
             <directory>/var/lib/tomcat8/webapps/${project.build.finalName}</directory>
             <sources>
               <source>
                 <location>${project.build.directory}/${project.build.finalName}</location>
               </source>
             </sources>
           </mapping>
         </mappings>
        </configuration>
      </plugin>
...

Now that the repository manager hosts a RPM package with your Java web application in a yum repository, you can configure yum on the target server to retrieve it for installation. You have to configure yum to include the repository as a package source. Depending on your specific Linux distribution, file paths and tools for this configuration will differ. A typical example would be to create a new file e.g. nexus.repo in /etc/yum.repos.d. A sample configuration for the public group can be found in Example yum source repository configuration.

Example yum source repository configuration
[nexus-public]
name=Nexus Releases Repository
baseurl=http://yournexusserverhost/nexus/content/groups/public
enabled=1
protect=0
gpgcheck=0
metadata_expire=30s
autorefresh=1
type=rpm-md

Once the configuration is added you can install or update any RPM packages from the repository manager as usual with yum install <packagename> or yum update <packagename>. This includes any required dependencies like a servlet container or a Java runtime as declared in the RPM Maven Plugin configuration and therefore the RPM/yum metadata.

Staging with RPMs

{inrmonly}

The Staging Suite of {pro} can be used with yum repositories allowing you to optimize the release process for your RPM packages.

The capability 'Yum: Staging Generate Metadata' allows you to configure yum for a 'Staging Profile'. Any staging repository created from a deployment via the staging profile is then automatically configured as a yum repository. The 'Aliases' configuration allows for the same mechanism as the capability 'Yum: Generate Metadata' documented earlier.

The capability 'Yum: Staging Merge Metadata' can be used to configure yum metadata creation for a build promotion profile and the attached repository groups.

If a staging repository or build promotion repository is configured for yum metadata generation and exposed via a repository group that is configured for yum metadata merging, the metadata from staging will be merged appropriately.