Project

General

Profile

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

runcible / README.md @ 524638e4

1
# Runcible
2

    
3
[![Build Status](https://secure.travis-ci.org/Katello/runcible.png)](http://travis-ci.org/Katello/runcible)
4
[![Coverage Status](https://coveralls.io/repos/github/Katello/runcible/badge.svg?branch=master)](https://coveralls.io/github/Katello/runcible?branch=master)
5

    
6
Exposing Pulp's juiciest parts. http://www.pulpproject.org/
7

    
8
Latest Live Tested Version: **pulp-server-2.11.0-1.el7.noarch**
9

    
10
Current stable Runcible: https://github.com/Katello/runcible/tree/0.3
11

    
12
For in-depth class and method documentation: http://katello.github.com/runcible/
13

    
14
Please file new issues here: [Redmine](http://projects.theforeman.org/projects/runcible/issues/new)
15

    
16
## 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
### Set Configuration
33

    
34
To use a single resource or extension, the configuration can be set:
35

    
36
    repo_api = Runcible::Resources::Repository.new({
37
                :url      => "",
38
                :api_path => "",
39
                :user     => "",
40
                :logger   => ""
41
              })
42
    repo_api.find(id)
43

    
44
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
     my_runcible.resources.repository.find(id)
54

    
55
Required Configuration:
56

    
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
Authentication Options are either HTTP or Oauth:
63

    
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
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

    
75
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

    
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
    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

    
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
    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

    
103
Alternatively, using distributor and importer objects:
104

    
105
    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

    
113
    Runcible::Extensions::Repository.new(config).create_with_importer_and_distributors("Repository_ID", importer, distributors)
114

    
115
## Testing
116

    
117
### 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
To run all tests using recorded data, run:
151

    
152
    rake test mode=none
153

    
154
To run all tests to record data:
155
   
156
    rake test mode=all
157

    
158
To run a single test using recorded data, run:
159
   
160
    rake test mode=none test=extensions/respository
161
    or (by filename)
162
    rake test mode=none test=./test/extensions/respository_test.rb
163

    
164
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
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
To run with  oauth, simply append the following to any commend:
172
   
173
    auth_type=oauth
174

    
175
To see RestClient logs while testing:
176
  
177
    logging=true
178

    
179
## Updating Documentation
180

    
181
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
## Building and Releasing
191

    
192
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
### 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
## 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
4. Ensure all tests are passing
247
5. Push to the branch (`git push origin my-new-feature`)
248
6. Create new Pull Request