Project

General

Profile

Download (8.8 KB) Statistics
| Branch: | Tag: | Revision:

runcible / README.md @ master

1 243b30b6 Eric D Helms
# Runcible
2
3 11715b4b Eric D. Helms
[![Build Status](https://secure.travis-ci.org/Katello/runcible.png)](http://travis-ci.org/Katello/runcible)
4 c22b9740 David Davis
[![Coverage Status](https://coveralls.io/repos/github/Katello/runcible/badge.svg?branch=master)](https://coveralls.io/github/Katello/runcible?branch=master)
5 11715b4b Eric D. Helms
6
Exposing Pulp's juiciest parts. http://www.pulpproject.org/
7 243b30b6 Eric D Helms
8 f6f75fb6 Partha Aji
Latest Live Tested Version: **pulp-server-2.19.0-0.1.alpha.201811111308gitcaafaee.el7.noarch**
9 db369a17 Eric D. Helms
10 49458300 Eric D. Helms
Current stable Runcible: https://github.com/Katello/runcible/tree/0.3
11
12 83531b29 Eric D. Helms
For in-depth class and method documentation: http://katello.github.com/runcible/
13
14 eff60dd2 Adam Price
Please file new issues here: [Redmine](http://projects.theforeman.org/projects/runcible/issues/new)
15 ed3a37ae Eric D. Helms
16 243b30b6 Eric D Helms
## Installation
17
18
Add this line to your application's Gemfile:
19
20
    gem 'runcible'
21
22
And then execute:
23
24
    $ bundle
25
26
Or install it yourself as:
27
28
    $ gem install runcible
29
30
## Usage
31
32 5731e8a7 Eric D. Helms
### Set Configuration
33
34 661ca339 Justin Sherrill
To use a single resource or extension, the configuration can be set:
35 5731e8a7 Eric D. Helms
36 661ca339 Justin Sherrill
    repo_api = Runcible::Resources::Repository.new({
37 5731e8a7 Eric D. Helms
                :url      => "",
38
                :api_path => "",
39
                :user     => "",
40
                :logger   => ""
41 661ca339 Justin Sherrill
              })
42
    repo_api.find(id)
43 5731e8a7 Eric D. Helms
44 661ca339 Justin Sherrill
Alternatively, a single 'server' instance which can easily use all 
45
  resources and extensions can be instantiated:
46
47
    my_runcible = Runcible::Instance.new({
48
                :url      => "",
49
                :api_path => "",
50
                :user     => "",
51
                :logger   => ""
52
              })
53 72db3c84 Dmitri Dolguikh
     my_runcible.resources.repository.find(id)
54 661ca339 Justin Sherrill
55
Required Configuration:
56 5731e8a7 Eric D. Helms
57
    :uri      => The base URI of the Pulp server (default: https://localhost)
58
    :api_path => The API path of the Pulp server (default: pulp/api/v2/)
59
    :user     => The Pulp username to be used in authentication
60
    :logger   => The location to log RestClient calls (e.g. stdout)
61
  
62 de6a916a Eric D. Helms
Authentication Options are either HTTP or Oauth:
63 5731e8a7 Eric D. Helms
64
    :http_auth  => {:password => ''}
65
66
    :oauth      => {:oauth_secret => "",
67
                    :oauth_key    => "" }
68
69
For an example on parsing the Pulp server.conf and using values provided within for the configuration see the [test_runner](https://github.com/Katello/runcible/blob/master/test/integration/test_runner.rb)
70
71
### Make a Request
72
73 661ca339 Justin Sherrill
Runcible provides two representations of Pulp entities to make API calls: [resources](https://github.com/Katello/runcible/tree/master/lib/runcible/resources) and [extensions](https://github.com/Katello/runcible/tree/master/lib/runcible/extensions)
74 5731e8a7 Eric D. Helms
75 de6a916a Eric D. Helms
The best examples of how to use either the resources or extensions can be found within the [tests](https://github.com/Katello/runcible/tree/master/test/integration)
76 5731e8a7 Eric D. Helms
77
#### Resources
78
79
Resources are designed to be one-for-one with the Pulp API calls in terms of required parameters and naming of the calls.  For example, in order to create a repository, associate a Yum importer and a distributor:
80
81 661ca339 Justin Sherrill
    my_runcible = Runcible::Instance.new(config)
82
    my_runcible.resources.repository.create("Repository_ID")
83
    my_runcible.resources.repository.associate_importer("Repository_ID", "yum_importer", {})
84
    my_runcible.resources.repository.associate_distributor("Repository_ID", "yum_distributor", {"relative_url" => "/", "http" => true, "https" => true})
85
86
    or
87
88
    Runcible::Resources::Repository.new(config).create("Repository_ID")
89
    Runcible::Resources::Repository.new(config).associate_importer("Repository_ID", "yum_importer", {})
90
    Runcible::Resources::Repository.new(config).associate_distributor("Repository_ID", "yum_distributor", {"relative_url" => "/", "http" => true, "https" => true})
91 5731e8a7 Eric D. Helms
92
#### Extensions
93
94
Extensions are constructs around the Pulp API that make retrieving, accessing or creating certain data types easier.  For example, providing objects that represent the details of a yum importer or distributor, and providing functions to create a Repository with an importer and distributors in a single call.  The same three step process above using extensions is:
95
96 661ca339 Justin Sherrill
    my_runcible = Runcible::Instance.new(config)
97
    my_runcible.extensions.repository.create_with_importer_and_distributor("Repository_ID", {:id=>'yum_importer'}, [{'type_id' => 'yum_distributor', 'id'=>'123', 'auto_publish'=>true, 'config'=>{'relative_url' => '/', 'http' => true, 'https' => true}}])
98
99
    or
100
101
    Runcible::Extensions::Repository.new(config).create_with_importer_and_distributors("Repository_ID", {:id=>'yum_importer'}, [{'type_id' => 'yum_distributor', 'id'=>'123', 'auto_publish'=>true, 'config'=>{'relative_url' => '/', 'http' => true, 'https' => true}}])
102 5731e8a7 Eric D. Helms
103
Alternatively, using distributor and importer objects:
104
105 661ca339 Justin Sherrill
    distributors = [Runcible::Models::YumDistributor.new('/path', true, true, :id => '123')]
106
    importer = Runcible::Models::YumImporter.new()
107
108
    my_runcible = Runcible::Instance.new(config)
109
    my_runcible.extensions.repository.create_with_importer_and_distributors("Repository_ID", importer, distributors)
110
111
    or
112 5731e8a7 Eric D. Helms
113 661ca339 Justin Sherrill
    Runcible::Extensions::Repository.new(config).create_with_importer_and_distributors("Repository_ID", importer, distributors)
114 243b30b6 Eric D Helms
115 12a95cc1 Justin Sherrill
## Testing
116
117 c279e034 David Davis
### Dependencies
118
119
In order to run and develop the ostree code in runcible locally, you will need
120
to install the pulp ostree packages (namely pulp-python-plugins and
121
pulp-ostree-plugins).
122
123
If you don't have ostree intalled already, you'll need to setup the ostree repo
124
as ostree is a dependency for pulp-ostree-plugins. For centos, you'll create
125
/etc/yum.repos.d/ostree.repo with this:
126
127
```
128
[atomic7-testing]
129
name=atomic7-testing
130
baseurl=http://cbs.centos.org/repos/atomic7-testing/x86_64/os/
131
gpgcheck=0
132
enabled=1
133
```
134
135
Now you should be able to install the two pulp plugin packages:
136
137
```
138
sudo yum install pulp-python-plugins pulp-ostree-plugins
139
```
140
141
Finally, update your pulp database and restart pulp:
142
143
```
144
sudo -u apache pulp-manage-db
145
for x in httpd pulp_resource_manager pulp_celerybeat pulp_workers; do sudo service $x restart; done
146
```
147
148
### Running Tests
149
150 12a95cc1 Justin Sherrill
To run all tests using recorded data, run:
151 de6a916a Eric D. Helms
152 27ba8849 Justin Sherrill
    rake test mode=none
153 12a95cc1 Justin Sherrill
154
To run all tests to record data:
155 de6a916a Eric D. Helms
   
156 e2989b74 Brad Buckingham
    rake test mode=all
157 12a95cc1 Justin Sherrill
158
To run a single test using recorded data, run:
159 de6a916a Eric D. Helms
   
160 27ba8849 Justin Sherrill
    rake test mode=none test=extensions/respository
161
    or (by filename)
162
    rake test mode=none test=./test/extensions/respository_test.rb
163 12a95cc1 Justin Sherrill
164 c279e034 David Davis
Note that when you record data, it's a good idea to delete any corresponding
165
vcr cassette files as recording data will sometimes only append to these files.
166
167 5c600f2f Eric D. Helms
To run tests against your live Pulp without recording a new cassette set record flag to false (does not apply to mode=none):
168
169
    record=false
170
171 12a95cc1 Justin Sherrill
To run with  oauth, simply append the following to any commend:
172 de6a916a Eric D. Helms
   
173
    auth_type=oauth
174 12a95cc1 Justin Sherrill
175 11715b4b Eric D. Helms
To see RestClient logs while testing:
176 de6a916a Eric D. Helms
  
177
    logging=true
178 12a95cc1 Justin Sherrill
179 dcec3cd2 Eric D Helms
## Updating Documentation
180 c9b73a63 Eric D. Helms
181 dcec3cd2 Eric D Helms
The documentation is built with yard and hosted on Github via the gh-pages branch of the repository. To update the documentation on Github:
182
183
    yard doc
184
    git checkout gh-pages
185
    cp -rf doc/* ./
186
    git add ./
187
    git commit -a -m 'Updating docs to version X.X'
188
    git push <upstream> gh-pages
189
    
190 c9b73a63 Eric D. Helms
## Building and Releasing
191
192 9f7ede0e Eric D Helms
An official release of Runcible should include the release of a gem on rubygems.org and an update to the documentation branch. At a minimum, the following two actions should be performed for each release:
193
194
1. [Build and Release Gem](#gem)
195
2. [Updating Documentation](#updating-documentation)
196
197 c9b73a63 Eric D. Helms
### Gem
198
199
While anyone can grab the source and build a new version of the gem, only those with Rubygems.org permissions on the project can release an official version.
200
201
To build a new version of Runcible, first bump the version depending on the type of release.
202
203
    cd runcible/
204
    vim lib/runcible/version.rb
205
206
Now update the version to the new version, and commit the changes.
207
208
    git commit -a -m 'Version bump'
209
210
Now build:
211
    
212
    gem build runcible.gemspec
213
214
215
#### Official Release
216
  
217
For an official release, again assuming you have the right permssions:
218
219
    gem push runcible-<version>.gem
220
221
### RPM Release
222
223
If you are wanting to generate a new RPM build, please make sure you have followed the steps above if the build is going to include new code.  All builds should first go in gem form to Rubygems.  You'll need to make sure tito is installed:
224
225
    yum install tito
226
227
Now tag, making sure the tag version matches the gem version:
228
229
    tito tag
230
231
Assuming you have the right dependencies available, you can do a local test build with tito (although we recommend using mock):
232
233
    tito build --test --rpm
234
235
With mock:
236
237
    tito build --test --rpm --builder=mock --builder-arg mock=<name_of_mock_config>
238
239
From here there are a variety of options to build and release an RPM pakaged version of Runcible (e.g. you can build an SRPM to feed to Koji, or use mock locally)
240
241 243b30b6 Eric D Helms
## Contributing
242
243
1. Fork it
244
2. Create your feature branch (`git checkout -b my-new-feature`)
245
3. Commit your changes (`git commit -am 'Added some feature'`)
246 5731e8a7 Eric D. Helms
4. Ensure all tests are passing
247
5. Push to the branch (`git push origin my-new-feature`)
248
6. Create new Pull Request