Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 368 lines (276 sloc) 14.822 kb
e12aa67a »
2012-09-28 fix links and headlines
1 # Nexus Yum Plugin
c2b47013 »
2012-09-28 migrate documentation for google code
2
3 A plugin for Sonatype Nexus 1.9.2.x or 2.X which recognizes RPMs in Nexus Maven repositories and generates
4 Yum metadata, so that RedHat-compatible system can use Nexus as software repository.
5
975c3ead »
2012-10-10 Update README.md
6 ## Content
7
8 1. [Audience](#audience)
9 1. [History](#history)
10 1. [Features](#features)
11 1. [Help & Issues](#help--issues)
12 1. [Installation](#installation)
13 1. [Configuration](#configuration)
9f374cd7 »
2012-10-11 first usage example
14 1. [Getting Started](#getting-started)
103d9f8b »
2012-10-18 staging examples with and without Nexus Pro
15 1. [Deploy Java Web Application via RPM](#deploy-java-web-application-via-rpm)
16 1. [Staging RPMs in Nexus Professional](#staging-rpms-in-nexus-professional)
17 1. [Staging RPMs in Nexus OSS](#staging-rpms-in-nexus-oss)
975c3ead »
2012-10-10 Update README.md
18 1. [How to Build](#how-to-build)
19
9f374cd7 »
2012-10-11 first usage example
20
e12aa67a »
2012-09-28 fix links and headlines
21 ## Audience
c2b47013 »
2012-09-28 migrate documentation for google code
22
23 The Nexus Yum Plugin is for all guys, who are deploying Java application for RedHat-compatible (RHEL, Centos, Fedora) servers and deploy via RPM.
24
25 ### Default use case
26
27 ![CLD at IS24][1]
9f374cd7 »
2012-10-11 first usage example
28 See [Deploy Java Web Application via RPM](#deploy-java-web-application-via-rpm).
c2b47013 »
2012-09-28 migrate documentation for google code
29
e12aa67a »
2012-09-28 fix links and headlines
30 ## History
c2b47013 »
2012-09-28 migrate documentation for google code
31
32 [Sonatype Nexus][2] is a common repository manager for [Maven][3], used by many companies to manage
33 their Java artifacts like JAR, WAR, pom.xml files. At [ImmobilienScout24][4] the DevOps-guys started
34 [to deploy their configurations][5] and
35 [java applications via RPMs][6] and
36 wanted to have a repository manager for their application RPMs. Why don't extend Sonatype Nexus to host RPMs as well?
37
e12aa67a »
2012-09-28 fix links and headlines
38 ## Features
c2b47013 »
2012-09-28 migrate documentation for google code
39
40 - Use a Maven repository, hosted in Nexus, containing RPMs as if it is a Yum repository. This leverages the virtual repository mechanism in Nexus which allows you to use Maven tooling to deploy RPMs into a Maven repository but still allow Yum clients to interact with the repository using the protocol it understands.
41 - Yum repositories are automatically updated if you upload/deploy/delete a new RPM into Nexus.
42 - Full group support so that you can logically group a set of Yum repositories behind a single URL.
43 - Have versioned views on repositories: <pre>http://your.nexus/nexus/service/local/yum/repos/releases/1.2.3/</pre> gives you a Yum repository with all packages in version *1.2.3* in repository releases.
44 - You can define aliases for specific versions eg. *production=1.2* and *testing=2.0* and access them via the alias: <pre>http://your.nexus/nexus/service/local/yum/repos/releases/testing/</pre> and <pre>http://your.nexus/nexus/service/local/yum/repos/releases/production/</pre> to get constant repository URLs for your servers. A new release is then applied to the server via setting the alias to a new version.
45 - Create Yum createrepo tasks manually via web interface.
46 - Multiple createrepo tasks on the same repository get merged.
47 - Use Yum group repositories as target of staging repositories (Nexus Pro)
48
e12aa67a »
2012-09-28 fix links and headlines
49 ## Help & Issues
c2b47013 »
2012-09-28 migrate documentation for google code
50
51 Ask for help at our [Google Group][7] or [create a new issue][8].
52
96367860 »
2012-09-28 fix headline
53 ## Installation
c2b47013 »
2012-09-28 migrate documentation for google code
54
55 1. [Install Sonatype Nexus][9]
56 1. Download latest *nexus-yum-plugin-bundle.zip* from our downloads page
57 1. Unzip the bundle to *$NEXUS_WORK_DIR/plugin-repository/*. The default for *$NEXUS_WORK_DIR* is *~/sonatype-work/nexus/*. For example:
58 unzip nexus-yum-plugin-1.13-bundle-zip -d $NEXUS_WORK_DIR/plugin-repository/
59 1. Install [createrepo][10] using your update manager (*yum*, *apt-get*, etc.) eg.
60 sudo yum install createrepo
61 1. Make sure that in *Nexus Adminstration --> Settings --> Application Server Settings (optional) --> Base URL* is set to a vaild URL like :
62 http://your.nexus.domain:8081/nexus
63 1. Sometimes *Force Base URL* is nessessary, too, see [ISSUE 4][11] . Otherwise the plugin can't determine the server URL and you got RPM locations like *null/content/repositories/*... in *primary.xml*.
64 1. Configure Nexus Yum Plugin via *yum.xml*. See Configuration.
65 1. Restart Nexus. Eg.
66 sudo service nexus stop
67 sudo service nexus start
68
69 Now the plugin should be installed.
70
e12aa67a »
2012-09-28 fix links and headlines
71 ## Configuration
c2b47013 »
2012-09-28 migrate documentation for google code
72
73 Here, you'll find everything about configuring Nexus Yum Plugin.
74
e12aa67a »
2012-09-28 fix links and headlines
75 ### Location
c2b47013 »
2012-09-28 migrate documentation for google code
76
77 The configuration of the Nexus Yum Plugin can be found in *yum.xml* in the same directory as *nexus.xml* :
78 $NEXUS_WORK_DIR/conf/yum.xml
79 Default:
80 ~/sonatype-work/nexus/conf/yum.xml
81
e12aa67a »
2012-09-28 fix links and headlines
82 ### Example
c2b47013 »
2012-09-28 migrate documentation for google code
83
84 Example *yum.xml*:
cf991a08 »
2012-10-11 Update README.md
85 ```xml
1cc9f437 »
2012-10-11 fix xml indention
86 <?xml version="1.0" encoding="UTF-8"?>
87 <configuration>
88 <!-- timeout for requests for a filtered (versionized) repository -->
89 <repositoryCreationTimeout>150</repositoryCreationTimeout><!-- in seconds -->
90
91 <!-- enables or disables the creation of a repository of repositories -->
92 <repositoryOfRepositoryVersionsActive>true</repositoryOfRepositoryVersionsActive>
93
94 <!-- enables or disables of delete rpm events via nexus -->
95 <deleteProcessing>true</deleteProcessing>
96
97 <!-- delay after which the rebuild of a repository is triggered in which one or more rpms got deleted -->
98 <delayAfterDeletion>10</delayAfterDeletion><!-- in seconds -->
99
100 <!-- configured aliases -->
101 <aliasMappings>
102 <aliasMapping>
103 <repoId>releases</repoId>
104 <alias>trunk</alias>
105 <version>5.1.15-2</version>
106 </aliasMapping>
107 <aliasMapping>
108 <repoId>releases</repoId>
109 <alias>production</alias>
110 <version>5.1.15-1</version>
111 </aliasMapping>
112 </aliasMappings>
113 </configuration>
cf991a08 »
2012-10-11 Update README.md
114 ```
115
9f374cd7 »
2012-10-11 first usage example
116 ## Getting Started
117
118 Here we provide some typical scenarios in which the _nexus-yum-plugin_ is used.
119
120 ### Deploy Java Web Application via RPM
121
122 #### Prepare the _pom.xml_
123
124 Assume you have a standard Java web application build with [Maven][3]. To build a RPM of your WAR file you could
fb5fac80 »
2012-10-11 small corrections
125 use the [rpm-maven-plugin][12] by Codehaus. Its goal _attached-rpm_ automatically attaches the RPM file as Maven
9f374cd7 »
2012-10-11 first usage example
126 build artifact so that the RPM is uploaded to Nexus in the _deploy_ phase. A minimal _pom.xml_ would look like this:
cf991a08 »
2012-10-11 Update README.md
127 ```xml
1cc9f437 »
2012-10-11 fix xml indention
128 <?xml version="1.0" encoding="UTF-8"?>
129 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
130 <modelVersion>4.0.0</modelVersion>
131 <groupId>org.sonatype.nexus.yum.its</groupId>
132 <artifactId>war-rpm-test</artifactId>
133 <version>1.0</version>
134 <packaging>war</packaging>
135 <build>
136 <plugins>
137 <!-- use rpm-maven-plugin to package the war into an rpm -->
138 <plugin>
139 <groupId>org.codehaus.mojo</groupId>
140 <artifactId>rpm-maven-plugin</artifactId>
141 <version>2.1-alpha-2</version>
142 <executions>
143 <execution>
144 <id>build-rpm</id>
145 <goals>
146 <!-- this goal automatically adds the rpm as Maven build artifact -->
147 <goal>attached-rpm</goal>
148 </goals>
149 </execution>
150 </executions>
151 <configuration>
152 <group>Applications/Internet</group>
153 <copyright>EPL</copyright>
154 <!-- require tomcat6 as webapp container -->
155 <requires>
156 <require>tomcat6</require>
157 </requires>
158 <mappings>
159 <mapping>
160 <!-- put webapp files to standard tomcat6 webapps directory -->
161 <directory>/var/lib/tomcat6/webapps/${project.build.finalName}</directory>
162 <sources>
163 <source>
164 <location>${project.build.directory}/${project.build.finalName}</location>
165 </source>
166 </sources>
167 </mapping>
168 </mappings>
169 </configuration>
170 </plugin>
171 </plugins>
172 </build>
173 <!-- deploy build artifacts (pom,war,rpm) to Nexus -->
174 <distributionManagement>
175 <repository>
176 <id>releases</id>
177 <name>Releases Repository</name>
178 <url>http://your.nexus.domain/nexus/content/repositories/releases</url>
179 </repository>
180 </distributionManagement>
181 </project>
cf991a08 »
2012-10-11 Update README.md
182 ```
9f374cd7 »
2012-10-11 first usage example
183
184 #### Deploy RPM to Nexus
185
186 If you have the _nexus-yum-plugin_ [installed](#installation) and deploy your application via
187
188 mvn deploy
189
190 to Nexus, the RPM is uploaded and on Nexus side the _yum_ metatdata is generated asynchronously. You can
191 browse the _yum_ metadata here:
192
193 http://your.nexus.domain/nexus/content/repositories/releases/repodata
194
195 #### Install RPM on Server
196
197 Your RPM was built and is stored in a Nexus _yum_ repository (if _nexus_yum_plugin_ is installed, each Maven
198 repository gets a _yum_ repository after uploading an RPM). The next step is to install the RPM on your RHEL-compatible server.
199
200 First of all, we need to introduce our new _yum_ repository to the server. Therefore, we create a new _yum repository file_ called
201 _nexus-releases.repo_. The default location for such _yum repository file_ is _/etc/yum.repos.d_, but may differ depending on
202 your distribution and configuration.:
203
204 sudo vi /etc/yum.repos.d/nexus-releases.repo
205
206 Insert the following content:
207
208 [nexus-releases]
209 name=Nexus Releases Repository
210 baseurl=http://your.nexus.domain/nexus/content/repositories/releases
211 enabled=1
212 protect=0
213 gpgcheck=0
214 metadata_expire=30s
215 autorefresh=1
216 type=rpm-md
217
218 and save the file. Now, the server will ask Nexus for new software packages and updates. After that just install your web application
219 and all its dependencies (Tomcat, Java, etc.) via:
220
221 sudo yum install war-rpm-test
222
223 and start tomcat:
224
225 sudo service tomcat start
226
227 That's it.
228
229 #### Update RPM
230
231 To update the web application on your server just call:
232
233 sudo service tomcat stop
234 sudo yum update
235 sudo service tomcat start
236
237 The tomcat restart is optional depending on your webapp and configuration, but always a good choice.
238
239 #### Summary
240
241 The _nexus-yum-plugin_ makes deploying Java application to _real_ RHEL-compatible servers really easy and works as a
242 relyable platform for your deployments.
c2b47013 »
2012-09-28 migrate documentation for google code
243
103d9f8b »
2012-10-18 staging examples with and without Nexus Pro
244 ### Staging RPMs in Nexus Professional
245
246 The [Staging Suite][13] in _Nexus Professional_ improves a stage-based release process a lot. The _Nexus Yum Plugin_ supports
247 this staging configuration, but requires some fine tuning to use the full feature list.
248
249 Image you want to configure a one-stage release process as described [in the Nexus book][14]. Follow the tutorial but use
250 _Maven2Yum_ as _Template_ for target repositories, staging profiles and group repositories. The advantage is that _Maven2Yum_
251 group repository really merges their member yum repositories by using [_mergerepo_][15]. This allows you to use these group
252 repositories with their constant url for _\*.repo_ files on the server.
253
254 ### Staging RPMs in Nexus OSS
255
256 The open source verion of _Nexus_ doesn't contain such a nice [Staging Suite][13], but you can stage your RPMs
257 (without the jar, war, etc. files) anyway.
258
259 Image you have 3 stages for your RPMs:
53b7e2ff »
2012-10-18 Update README.md
260
103d9f8b »
2012-10-18 staging examples with and without Nexus Pro
261 1. _development_
262 1. _test & verification_
263 1. _production_
53b7e2ff »
2012-10-18 Update README.md
264
103d9f8b »
2012-10-18 staging examples with and without Nexus Pro
265 and already a RPM package in version 1.0 in your repository called _releases_.
266
267 #### Create aliases
268
269 First of all you create version aliases for each stage. These aliases allow you to have a canonical repository url for each stage.
270 You can use _curl_ for the initial creation:
53b7e2ff »
2012-10-18 Update README.md
271
103d9f8b »
2012-10-18 staging examples with and without Nexus Pro
272 curl -d "1.0" --header "Content-Type: text/plain" http://your.nexus.domain/nexus/service/local/yum/alias/releases/development/
273 curl -d "1.0" --header "Content-Type: text/plain" http://your.nexus.domain/nexus/service/local/yum/alias/releases/verification/
274 curl -d "1.0" --header "Content-Type: text/plain" http://your.nexus.domain/nexus/service/local/yum/alias/releases/production/
275
276 #### Prepare servers
277
278 Now, you are able to add these alias repositories to your server.
279 On your _development_ machine create a file named _/etc/yum.repos.d/nexus-dev.repo_ and the following content:
53b7e2ff »
2012-10-18 Update README.md
280
103d9f8b »
2012-10-18 staging examples with and without Nexus Pro
281 [nexus-dev]
282 name=Nexus Dev Repository
283 baseurl=http://your.nexus.domain/nexus/service/local/yum/repos/releases/development/
284 enabled=1
285 protect=0
286 gpgcheck=0
287 metadata_expire=30s
288 autorefresh=1
289 type=rpm-md
53b7e2ff »
2012-10-18 Update README.md
290
103d9f8b »
2012-10-18 staging examples with and without Nexus Pro
291 On your _verification_ machine create a file named _/etc/yum.repos.d/nexus-verification.repo_ and the following content:
53b7e2ff »
2012-10-18 Update README.md
292
103d9f8b »
2012-10-18 staging examples with and without Nexus Pro
293 [nexus-verification]
294 name=Nexus Verification Repository
295 baseurl=http://your.nexus.domain/nexus/service/local/yum/repos/releases/verification/
296 enabled=1
297 protect=0
298 gpgcheck=0
299 metadata_expire=30s
300 autorefresh=1
301 type=rpm-md
53b7e2ff »
2012-10-18 Update README.md
302
103d9f8b »
2012-10-18 staging examples with and without Nexus Pro
303 On your _production_ machine create a file named _/etc/yum.repos.d/nexus-production.repo_ and the following content:
53b7e2ff »
2012-10-18 Update README.md
304
103d9f8b »
2012-10-18 staging examples with and without Nexus Pro
305 [nexus-production]
306 name=Nexus Production Repository
307 baseurl=http://your.nexus.domain/nexus/service/local/yum/repos/releases/production/
308 enabled=1
309 protect=0
310 gpgcheck=0
311 metadata_expire=30s
312 autorefresh=1
313 type=rpm-md
314
315 #### Promote RPM through Stages
316
317 Now, it's time to deploy version 2.0 of your software RPM to the _releases_ repository. To install this RPM on your
318 _development_ machine, update your version alias first:
319
320 curl -d "2.0" --header "Content-Type: text/plain" http://your.nexus.domain/nexus/service/local/yum/alias/releases/development/
321
322 Afterwards, login to your machine and update your software RPM via
323
324 sudo yum update
325
326 After your integration or whatever tests verified the _development_ machine, you can promote the RPM to _verification_ stage:
327
328 curl -d "2.0" --header "Content-Type: text/plain" http://your.nexus.domain/nexus/service/local/yum/alias/releases/verification/
329
330 Run again _sudo yum update_ on the _verification_ machine and test your software RPM in that environment.
331 Finally, if everything is green, you can stage this RPM to _production_.
332
333 curl -d "2.0" --header "Content-Type: text/plain" http://your.nexus.domain/nexus/service/local/yum/alias/releases/production/
334
335 and run _sudo yum update_ on your _production_ machine.
336
337 #### Summary
338
339 Version aliases let you create versionized views on your Maven RPM repositories, which is useful your RPM staging, but
340 don't let you stage your whole bunch of artifacts like RPMs, JARs, WARs, Docs, etc. together. For this you need _Nexus Professional_.
341
e12aa67a »
2012-09-28 fix links and headlines
342 ## How to build
c2b47013 »
2012-09-28 migrate documentation for google code
343
9f374cd7 »
2012-10-11 first usage example
344 The build process is based on [Apache Maven 3][3]. You must have [createrepo][10] installed in order to execute all
345 the integration tests. Just do a
c2b47013 »
2012-09-28 migrate documentation for google code
346
347 mvn package
348
349 to run all tests and create a plugin bundle.
350
e12aa67a »
2012-09-28 fix links and headlines
351 [1]: https://raw.github.com/sonatype/nexus-yum-plugin/master/docs/images/NeuxsYumPlugin.png
c2b47013 »
2012-09-28 migrate documentation for google code
352 [2]: http://nexus.sonatype.org
353 [3]: http://maven.apache.org
354 [4]: http://www.immobilienscout24.de
355 [5]: http://blog.schlomo.schapiro.org/2011/05/configuration-management-with.html
356 [6]: http://www.slideshare.net/actionjackx/automated-java-deployments-with-rpm
357 [7]: https://groups.google.com/group/nexus-yum-plugin/
358 [8]: https://github.com/sonatype/nexus-yum-plugin/issues/new
359 [9]: http://www.sonatype.com/books/nexus-book/reference/install-sect-install.html
360 [10]: http://createrepo.baseurl.org/
361 [11]: http://code.google.com/p/nexus-yum-plugin/issues/detail?id=4
9f374cd7 »
2012-10-11 first usage example
362 [12]: http://mojo.codehaus.org/rpm-maven-plugin/
103d9f8b »
2012-10-18 staging examples with and without Nexus Pro
363 [13]: http://www.sonatype.com/books/nexus-book/reference/staging-sect-intro.html
364 [14]: http://www.sonatype.com/books/nexus-book/reference/staging-sect-prepare-nexus.html
365 [15]: http://linux.die.net/man/1/mergerepo
366
367
Something went wrong with that request. Please try again.