Project

General

Profile

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

foreman_docker / README.md @ cefce4bc

1 d4e021f3 Amos Benari
# Foreman Docker Plugin
2
3 944fd8e7 Daniel Lobato García
[![Code Climate](https://codeclimate.com/github/theforeman/foreman-docker/badges/gpa.svg)](https://codeclimate.com/github/theforeman/foreman-docker)
4
[![Gem Version](https://badge.fury.io/rb/foreman_docker.svg)](http://badge.fury.io/rb/foreman_docker)
5
[![Dependency Status](https://gemnasium.com/theforeman/foreman-docker.svg)](https://gemnasium.com/theforeman/foreman-docker)
6 5688d841 Daniel Lobato García
[![Issue Stats](http://issuestats.com/github/theforeman/foreman-docker/badge/pr)](http://issuestats.com/github/theforeman/foreman-docker)
7 944fd8e7 Daniel Lobato García
8 ab73d5cf Daniel Lobato
```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.
9
10
* Website: [TheForeman.org](http://theforeman.org)
11
* ServerFault tag: [Foreman](http://serverfault.com/questions/tagged/foreman)
12
* Issues: [foreman_docker Redmine](http://projects.theforeman.org/projects/docker/issues)
13
* Wiki: [Foreman wiki](http://projects.theforeman.org/projects/foreman/wiki/About)
14
* Community and support: #theforeman for general support, #theforeman-dev for development chat in [Freenode](irc.freenode.net)
15
* Mailing lists:
16
    * [foreman-users](https://groups.google.com/forum/?fromgroups#!forum/foreman-users)
17
    * [foreman-dev](https://groups.google.com/forum/?fromgroups#!forum/foreman-dev)
18
19
## Features
20
21
* Special view with logs and processes of Foreman managed containers
22
    ![](http://i.imgur.com/D21bdgj.png)
23
    ![](http://i.imgur.com/XnrPTZC.png)
24
* Wizard for container creation and cgroups configuration
25
    ![Select a docker image](http://i.imgur.com/IoMuNnr.png)
26
    ![Cgroups configuration](http://i.imgur.com/74d99Tf.png)
27
* Commit and upload containers: creates an image with the status of your current container
28
    ![Commit and upload to the docker hub](http://i.imgur.com/coF5Y0L.png)
29
* Container listing and basic CRUD operations
30
    ![](http://i.imgur.com/DPcaHkZ.png)
31
32
### Planned
33 7cb2291f Tim Meusel
* [Kubernetes](https://github.com/kubernetes/kubernetes/) integration
34 ab73d5cf Daniel Lobato
* Events stream ([#8037](http://projects.theforeman.org/issues/8037))
35
* 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))
36
* Quickstart images - pre-supplied images and configuration ([#7869](http://projects.theforeman.org/issues/7869))
37
* Links to other containers ([#7866](http://projects.theforeman.org/issues/7866))
38
* API ([#7874](http://projects.theforeman.org/issues/7874))
39
* [Hammer CLI](http://github.com/theforeman/hammer-cli-foreman) support ([#8227](http://projects.theforeman.org/issues/8227))
40 d4e021f3 Amos Benari
41
## Installation
42
43 6953746a Dominic Cleal
Please see the Foreman manual for appropriate instructions:
44 d4e021f3 Amos Benari
45 6953746a Dominic Cleal
* [Foreman: How to Install a Plugin](http://theforeman.org/manuals/latest/index.html#6.1InstallaPlugin)
46 d4e021f3 Amos Benari
47 ab73d5cf Daniel Lobato
### Red Hat, CentOS, Fedora, Scientific Linux (rpm)
48 d4e021f3 Amos Benari
49 ab73d5cf Daniel Lobato
Set up the repo as explained in the link above, then run
50 f1f3bc98 Dominic Cleal
51 ab73d5cf Daniel Lobato
    # yum install ruby193-rubygem-foreman_docker
52
53
### Debian, Ubuntu (deb)
54
55
Set up the repo as explained in the link above, then run
56
57
    # apt-get install ruby-foreman-docker
58
59
### Bundle (gem)
60
61
Add the following to bundler.d/Gemfile.local.rb in your Foreman installation directory (/usr/share/foreman by default)
62
63
    $ gem 'foreman_docker'
64
65
Then run `bundle install` and `foreman-rake db:migrate` from the same directory
66
67
--------------
68
69
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
70
71
![](http://i.imgur.com/Ug14Ktl.png)
72
73
## Configuration
74
75
Go to **Infrastructure > Compute Resources** and click on "New Compute Resource".
76
77
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.
78
79
That's it. You're now ready to create and manage containers in your new Docker compute resource.
80 8616f50f pujan14
81 d4e021f3 Amos Benari
## Compatibility
82
83 ab73d5cf Daniel Lobato
| Foreman | Plugin |
84 d4e021f3 Amos Benari
| ---------------:| --------------:|
85 ab73d5cf Daniel Lobato
| >= 1.5         | 0.0.1 - 0.0.3   |
86
| >= 1.6         | 0.1.0 - 0.2.0   |
87 59460788 Daniel Lobato
| >= 1.7         | 1.0.0 - 2.1.1   |
88
| >= 1.7         | 3.0.0+          |
89 94a7c441 Daniel Lobato Garcia
| >= 1.15        | 3.1.0+          |
90 eb0c6d28 Daniel Lobato
91 b9eb4615 Sebastian Gräßl
## Docker Registry API Compatibility
92
93
| Plugin version | Registry API version |
94
| ---------------:| --------------:|
95
| <  3.1.0        | [v1](http://docs.master.dockerproject.org/v1.7/reference/api/registry_api/)             |
96
| >= 3.1.0        | [v1](http://docs.master.dockerproject.org/v1.7/reference/api/registry_api/), [v2](https://docs.docker.com/registry/spec/api/)*****    |
97
98
_*** Note:** API v2 as default and v1 to fall back on._
99
100 741cff16 Daniel Lobato
See extras/RELEASE.md for more detailed information on compatibility and releases.
101 ab73d5cf Daniel Lobato
102
## How to contribute?
103 466cd5ba Daniel Lobato
104 ab73d5cf Daniel Lobato
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:
105 5dc4f6d6 Daniel Lobato
* 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.
106 ab73d5cf Daniel Lobato
* [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.
107
* [Rubocop](https://github.com/bbatsov/rubocop) will analyze your code, you can run it locally with `rake rubocop`.
108
* 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
109
110
111
### Testing
112
113
Run `rake test:docker` from your Foreman directory to run the test suite.
114 466cd5ba Daniel Lobato
115 d4e021f3 Amos Benari
## Latest code
116
117
You can get the develop branch of the plugin by specifying your Gemfile in this way:
118
119 d8acfb64 Martin Loy
    gem 'foreman_docker', :git => "https://github.com/theforeman/foreman-docker.git"
120 d4e021f3 Amos Benari
121
# Copyright
122
123 6953746a Dominic Cleal
Copyright (c) 2014 Amos Benari
124
125
This program is free software: you can redistribute it and/or modify
126
it under the terms of the GNU General Public License as published by
127
the Free Software Foundation, either version 3 of the License, or
128
(at your option) any later version.
129
130
This program is distributed in the hope that it will be useful,
131
but WITHOUT ANY WARRANTY; without even the implied warranty of
132
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
133
GNU General Public License for more details.
134
135
You should have received a copy of the GNU General Public License
136
along with this program.  If not, see <http://www.gnu.org/licenses/>.