diff --git a/plugins/providers/docker/README.md b/plugins/providers/docker/README.md deleted file mode 100644 index e83e5efae..000000000 --- a/plugins/providers/docker/README.md +++ /dev/null @@ -1,206 +0,0 @@ -# docker-provider - -[![Build Status](https://travis-ci.org/fgrehm/docker-provider.png?branch=master)](https://travis-ci.org/fgrehm/docker-provider) [![Gem Version](https://badge.fury.io/rb/docker-provider.png)](http://badge.fury.io/rb/docker-provider) [![Gittip](http://img.shields.io/gittip/fgrehm.svg)](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