providers/docker: Remove old README
This commit is contained in:
Fabio Rehm
Mitchell Hashimoto
parent
2d88e3a1c3
commit
de588ba82c
|
|
@ -1,206 +0,0 @@
|
|||
# docker-provider
|
||||
|
||||
[](https://travis-ci.org/fgrehm/docker-provider) [](http://badge.fury.io/rb/docker-provider) [](https://www.gittip.com/fgrehm/)
|
||||
|
||||
A [Docker](http://www.docker.io/) provider for [Vagrant](http://www.vagrantup.com/)
|
||||
1.4+.
|
||||
|
||||
|
||||
## Warning
|
||||
|
||||
This is experimental, expect things to break.
|
||||
|
||||
|
||||
## Requirements
|
||||
|
||||
* Vagrant 1.4+
|
||||
* Docker 0.7.0+
|
||||
|
||||
|
||||
## Features
|
||||
|
||||
* Support for Vagrant's `up`, `destroy`, `halt`, `reload` and `ssh` commands
|
||||
* Port forwarding
|
||||
* Synced / shared folders support
|
||||
* Set container hostnames from Vagrantfiles
|
||||
* Provision Docker containers with any built-in Vagrant provisioner (as long as the container has a SSH server running)
|
||||
|
||||
You can see the plugin in action by watching the following asciicasts I published
|
||||
prior to releasing 0.0.1:
|
||||
|
||||
* http://asciinema.org/a/6162
|
||||
* http://asciinema.org/a/6177
|
||||
|
||||
|
||||
## Getting started
|
||||
|
||||
If you are on a Mac / Windows machine, please fire up a x64 Linux VM with Docker +
|
||||
Vagrant 1.4+ installed or use [this Vagrantfile](https://gist.github.com/fgrehm/fc48fb51ec7df64439e4)
|
||||
and follow the instructions from within the VM.
|
||||
|
||||
_It is likely that the plugin works with [boot2docker](http://boot2docker.github.io/)
|
||||
but I personally haven't tried that yet. If you are able to give it a go please
|
||||
[let me know](https://github.com/fgrehm/docker-provider/issues/new)._
|
||||
|
||||
### Initial setup
|
||||
|
||||
_If you are trying things out from a Vagrant VM using the `Vagrantfile` gisted
|
||||
above, you can skip to the next section_
|
||||
|
||||
The plugin requires Docker's executable to be available on current user's `PATH`
|
||||
and that the current user has been added to the `docker` group since we are not
|
||||
using `sudo` when interacting with Docker's CLI. For more information on setting
|
||||
this up please check [this page](http://docs.docker.io/en/latest/installation/ubuntulinux/#giving-non-root-access).
|
||||
|
||||
### `vagrant up`
|
||||
|
||||
On its current state, the plugin is not "user friendly" and won't provide any kind
|
||||
of feedback about the process of downloading Docker images, so before you add a
|
||||
`docker-provider` [base box](http://docs.vagrantup.com/v2/boxes.html) it is recommended
|
||||
that you `docker pull` the associated base box images prior to spinning up `docker-provider`
|
||||
containers (otherwise you'll be staring at a blinking cursor without any progress
|
||||
information for a while).
|
||||
|
||||
Assuming you have Vagrant 1.4+ and Docker 0.7.0+ installed just sing that same
|
||||
old song:
|
||||
|
||||
```sh
|
||||
vagrant plugin install docker-provider
|
||||
docker pull fgrehm/vagrant-ubuntu:precise
|
||||
vagrant box add precise64 http://bit.ly/vagrant-docker-precise
|
||||
vagrant init precise64
|
||||
vagrant up --provider=docker
|
||||
```
|
||||
|
||||
Under the hood, that base box will [configure](#configuration) `docker-provider`
|
||||
to use the [`fgrehm/vagrant-ubuntu:precise`](https://index.docker.io/u/fgrehm/vagrant-ubuntu/)
|
||||
image that approximates a standard Vagrant box (`vagrant` user, default SSH key,
|
||||
etc.) and you should be good to go.
|
||||
|
||||
|
||||
## Using custom images
|
||||
|
||||
If you want to use a custom Docker image without creating a Vagrant base box,
|
||||
you can use a "dummy" box and configure things from your `Vagrantfile` like
|
||||
in [vagrant-digitalocean](https://github.com/smdahlen/vagrant-digitalocean#configure)
|
||||
or [vagrant-aws](https://github.com/mitchellh/vagrant-aws#quick-start):
|
||||
|
||||
```ruby
|
||||
Vagrant.configure("2") do |config|
|
||||
config.vm.box = "dummy"
|
||||
config.vm.box_url = "http://bit.ly/vagrant-docker-dummy"
|
||||
config.vm.provider :docker do |docker|
|
||||
docker.image = "your/image:tag"
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
|
||||
## Configuration
|
||||
|
||||
This provider exposes a few provider-specific configuration options
|
||||
that are passed on to `docker run` under the hood when the container
|
||||
is being created:
|
||||
|
||||
* `image` - Docker image to run (required)
|
||||
* `privileged` - Give extended privileges to the container (defaults to false)
|
||||
* `cmd` - An array of strings that makes up for the command to run the container (defaults to what has been set on your `Dockerfile` as `CMD` or `ENTRYPOINT`)
|
||||
* `ports` - An array of strings that makes up for the mapped network ports
|
||||
* `volumes` - An array of strings that makes up for the data volumes used by the container
|
||||
|
||||
These can be set like typical provider-specific configuration:
|
||||
|
||||
```ruby
|
||||
Vagrant.configure("2") do |config|
|
||||
# ... other stuff
|
||||
|
||||
config.vm.provider :docker do |docker|
|
||||
docker.image = 'fgrehm/vagrant-ubuntu-dind:precise'
|
||||
docker.privileged = true
|
||||
docker.cmd = ['/dind', '/sbin/init']
|
||||
|
||||
docker.ports << '1234:22'
|
||||
docker.volumes << '/var/lib/docker'
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
|
||||
## Networks
|
||||
|
||||
Networking features in the form of `config.vm.network` are not supported with
|
||||
`docker-provider` apart from [forwarded ports]().
|
||||
If any of [`:private_network`](http://docs.vagrantup.com/v2/networking/private_network.html)
|
||||
or [`:public_network`](http://docs.vagrantup.com/v2/networking/public_network.html)
|
||||
are specified, Vagrant **won't** emit a warning.
|
||||
|
||||
The same applies to changes on forwarded ports after the container has been
|
||||
created, Vagrant **won't** emit a warning to let you know that the ports specified
|
||||
on your `Vagrantfile` differs from what has been passed on to `docker run` when
|
||||
creating the container.
|
||||
|
||||
_At some point the plugin will emit warnings on the scenarios described above, but
|
||||
not on its current state. Pull Requests are encouraged ;)_
|
||||
|
||||
|
||||
## Synced Folders
|
||||
|
||||
There is support for synced folders on the form of [Docker volumes](http://docs.docker.io/en/latest/use/working_with_volumes/#mount-a-host-directory-as-a-container-volume)
|
||||
but as with forwarded ports, you won't be able to change them after the container
|
||||
has been created. [NFS](http://docs.vagrantup.com/v2/synced-folders/nfs.html)
|
||||
synced folders are also supported (as long as you set the `privileged`
|
||||
[config](#configuration) to true so that `docker-provider` can mount it on the
|
||||
guest container) and are capable of being reconfigured between `vagrant reload`s
|
||||
(different from Docker volumes).
|
||||
|
||||
This is good enough for all built-in Vagrant provisioners (shell,
|
||||
chef, and puppet) to work!
|
||||
|
||||
_At some point the plugin will emit warnings when the configured `Vagrantfile`
|
||||
synced folders / volumes differs from the ones used upon the container creation,
|
||||
but not on its current state. Pull Requests are encouraged ;)_
|
||||
|
||||
|
||||
## Box format
|
||||
|
||||
Every provider in Vagrant must introduce a custom box format. This provider introduces
|
||||
`docker` boxes and you can view some examples in the [`boxes`](boxes) directory.
|
||||
That directory also contains instructions on how to build them.
|
||||
|
||||
The box format is basically just the required `metadata.json` file along with a
|
||||
`Vagrantfile` that does default settings for the provider-specific configuration
|
||||
for this provider.
|
||||
|
||||
|
||||
## Available base boxes
|
||||
|
||||
| LINK | DESCRIPTION |
|
||||
| --- | --- |
|
||||
| http://bit.ly/vagrant-docker-precise | Ubuntu 12.04 Precise x86_64 with Puppet and Chef preinstalled and configured to run `/sbin/init` |
|
||||
| http://bit.ly/vagrant-docker-precise-dind | Ubuntu 12.04 Precise x86_64 based on the box above and ready to run [DinD](https://github.com/jpetazzo/dind) |
|
||||
|
||||
|
||||
## Limitations
|
||||
|
||||
As explained on the [networks](#networks) and [synced folder](#synced-folders)
|
||||
sections above, there are some "gotchas" when using the plugin that you need to have
|
||||
in mind before you start to pull your hair out.
|
||||
|
||||
For instance, forwarded ports, synced folders and containers' hostnames will not be
|
||||
reconfigured on `vagrant reload`s if they have changed and the plugin **_will not
|
||||
give you any kind of warning or message_**. As an example, if you change your Puppet
|
||||
manifests / Chef cookbooks paths (which are shared / synced folders under the hood),
|
||||
**_you'll need to start from scratch_** (unless you make them NFS shared folders).
|
||||
This is due to a limitation in Docker itself as we can't change those parameters
|
||||
after the container has been created.
|
||||
|
||||
Forwarded ports automatic collision handling is **_not supported as well_**.
|
||||
|
||||
|
||||
## Contributing
|
||||
|
||||
1. Fork it
|
||||
2. Create your feature branch (`git checkout -b my-new-feature`)
|
||||
3. Commit your changes (`git commit -am 'Add some feature'`)
|
||||
4. Push to the branch (`git push origin my-new-feature`)
|
||||
5. Create new Pull Request
|
||||
Loading…
Reference in New Issue