Project

General

Profile

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

foreman_docker / README.md @ ff114977

1
# Foreman Docker Plugin
2

    
3
**This plugin has been discontinued. The latest release only helps with its removal. If you're interested in taking over the maintanance, let us know.**
4

    
5
In order to remove the plugin from you Foreman installation, following steps need to be taken
6

    
7
1. make a backup
8
1. upgrade to last version of foreman-docker 5.0 (and Katello if you're using it)
9
1. run `foreman-rake db:migrate` (if you have Katello, this will erase docker data)
10
1. run `foreman-rake foreman_docker:cleanup` (cleans up all data that this plugin introduced)
11
1. `yum remove tfm-rubygem-foreman_docker` or `apt remove ruby-foreman-docker`
12
1. `yum remove tfm-rubygem-hammer_cli_foreman_docker` or `apt remove ruby-hammer-cli-foreman-docker` unless you still use katello commands from it
13
1. update apipie cache `foreman-rake apipie:cache`
14
1. `service httpd restart`
15

    
16

    
17
[![Code Climate](https://codeclimate.com/github/theforeman/foreman-docker/badges/gpa.svg)](https://codeclimate.com/github/theforeman/foreman-docker)
18
[![Gem Version](https://badge.fury.io/rb/foreman_docker.svg)](http://badge.fury.io/rb/foreman_docker)
19
[![Dependency Status](https://gemnasium.com/theforeman/foreman-docker.svg)](https://gemnasium.com/theforeman/foreman-docker)
20
[![Issue Stats](http://issuestats.com/github/theforeman/foreman-docker/badge/pr)](http://issuestats.com/github/theforeman/foreman-docker)
21

    
22
```foreman_docker``` enables provisioning and managing of [Docker](http://docker.com) containers and images in [Foreman](http://github.com/theforeman/foreman), all of that under the GPL v3+ license.
23

    
24
* Website: [TheForeman.org](http://theforeman.org)
25
* ServerFault tag: [Foreman](http://serverfault.com/questions/tagged/foreman)
26
* Issues: [foreman_docker Redmine](http://projects.theforeman.org/projects/docker/issues)
27
* Wiki: [Foreman wiki](http://projects.theforeman.org/projects/foreman/wiki/About)
28
* Community and support: #theforeman for general support, #theforeman-dev for development chat in [Freenode](irc.freenode.net)
29
* Mailing lists:
30
    * [foreman-users](https://groups.google.com/forum/?fromgroups#!forum/foreman-users)
31
    * [foreman-dev](https://groups.google.com/forum/?fromgroups#!forum/foreman-dev)
32

    
33
## Features
34

    
35
* Special view with logs and processes of Foreman managed containers
36
    ![](http://i.imgur.com/D21bdgj.png)
37
    ![](http://i.imgur.com/XnrPTZC.png)
38
* Wizard for container creation and cgroups configuration
39
    ![Select a docker image](http://i.imgur.com/IoMuNnr.png)
40
    ![Cgroups configuration](http://i.imgur.com/74d99Tf.png)
41
* Commit and upload containers: creates an image with the status of your current container
42
    ![Commit and upload to the docker hub](http://i.imgur.com/coF5Y0L.png)
43
* Container listing and basic CRUD operations
44
    ![](http://i.imgur.com/DPcaHkZ.png)
45

    
46
### Planned
47
* [Kubernetes](https://github.com/kubernetes/kubernetes/) integration
48
* Events stream ([#8037](http://projects.theforeman.org/issues/8037))
49
* Tight integration between Docker hosts [Atomic](http://www.projectatomic.io/) and [CoreOS](http://coreos.com/) and containers ([#7653](http://projects.theforeman.org/issues/7653), [#7652](http://projects.theforeman.org/issues/7652))
50
* Quickstart images - pre-supplied images and configuration ([#7869](http://projects.theforeman.org/issues/7869))
51
* Links to other containers ([#7866](http://projects.theforeman.org/issues/7866))
52
* API ([#7874](http://projects.theforeman.org/issues/7874))
53
* [Hammer CLI](http://github.com/theforeman/hammer-cli-foreman) support ([#8227](http://projects.theforeman.org/issues/8227))
54

    
55
## Installation
56

    
57
Please see the Foreman manual for appropriate instructions:
58

    
59
* [Foreman: How to Install a Plugin](http://theforeman.org/manuals/latest/index.html#6.1InstallaPlugin)
60

    
61
### Red Hat, CentOS, Fedora, Scientific Linux (rpm)
62

    
63
Set up the repo as explained in the link above, then run
64

    
65
    # yum install ruby193-rubygem-foreman_docker
66

    
67
### Debian, Ubuntu (deb)
68

    
69
Set up the repo as explained in the link above, then run
70

    
71
    # apt-get install ruby-foreman-docker
72

    
73
### Bundle (gem)
74

    
75
Add the following to bundler.d/Gemfile.local.rb in your Foreman installation directory (/usr/share/foreman by default)
76

    
77
    $ gem 'foreman_docker'
78

    
79
Then run `bundle install` and `foreman-rake db:migrate` from the same directory
80

    
81
--------------
82

    
83
To verify that the installation was successful, go to Foreman, top bar **Administer > About** and check 'foreman_docker' shows up in the **System Status** menu under the Plugins tab. You should also see a **'Containers'** button show up in the top bar, similar to this
84

    
85
![](http://i.imgur.com/Ug14Ktl.png)
86

    
87
## Configuration
88

    
89
Go to **Infrastructure > Compute Resources** and click on "New Compute Resource".
90

    
91
Choose the **Docker provider**, and fill in all the fields. User name, password, and email are used so that Docker clients such as Foreman can make the host download images from the Docker hub. Your password will be encrypted in the database.
92

    
93
That's it. You're now ready to create and manage containers in your new Docker compute resource.
94

    
95
## Compatibility
96

    
97
| Foreman | Plugin |
98
| ---------------:| --------------:|
99
| >= 1.5         | 0.0.1 - 0.0.3   |
100
| >= 1.6         | 0.1.0 - 0.2.0   |
101
| >= 1.7         | 1.0.0 - 2.1.1   |
102
| >= 1.7         | 3.0.0+          |
103
| >= 1.15        | 3.1.0+          |
104

    
105
## Docker Registry API Compatibility
106

    
107
| Plugin version | Registry API version |
108
| ---------------:| --------------:|
109
| <  3.1.0        | [v1](http://docs.master.dockerproject.org/v1.7/reference/api/registry_api/)             |
110
| >= 3.1.0        | [v1](http://docs.master.dockerproject.org/v1.7/reference/api/registry_api/), [v2](https://docs.docker.com/registry/spec/api/)*****    |
111

    
112
_*** Note:** API v2 as default and v1 to fall back on._
113

    
114
See extras/RELEASE.md for more detailed information on compatibility and releases.
115

    
116
## How to contribute?
117

    
118
Generally, follow the [Foreman guidelines](http://theforeman.org/contribute.html). For code-related contributions, fork this project and send a pull request with all changes. Some things to keep in mind:
119
* Code from the master branch can contain features only present in [Fog's](http://github.com/fog/fog) master branch, we commit to wait for the next Fog release to put that code in a foreman-docker release.
120
* [Follow the rules](http://theforeman.org/contribute.html#SubmitPatches) about commit message style and create a Redmine issue. Doing this right will help reviewers to get your contribution merged faster.
121
* [Rubocop](https://github.com/bbatsov/rubocop) will analyze your code, you can run it locally with `rake rubocop`.
122
* All of our pull requests run the full test suite in our [Jenkins CI system](http://ci.theforeman.org/). Please include tests in your pull requests for any additions or changes in functionality
123

    
124

    
125
### Testing
126

    
127
Run `rake test:docker` from your Foreman directory to run the test suite.
128

    
129
## Latest code
130

    
131
You can get the develop branch of the plugin by specifying your Gemfile in this way:
132

    
133
    gem 'foreman_docker', :git => "https://github.com/theforeman/foreman-docker.git"
134

    
135
# Copyright
136

    
137
Copyright (c) 2014 Amos Benari
138

    
139
This program is free software: you can redistribute it and/or modify
140
it under the terms of the GNU General Public License as published by
141
the Free Software Foundation, either version 3 of the License, or
142
(at your option) any later version.
143

    
144
This program is distributed in the hope that it will be useful,
145
but WITHOUT ANY WARRANTY; without even the implied warranty of
146
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
147
GNU General Public License for more details.
148

    
149
You should have received a copy of the GNU General Public License
150
along with this program.  If not, see <http://www.gnu.org/licenses/>.