website/docs: docker provider
This commit is contained in:
Mitchell Hashimoto
parent
cadd7f602c
commit
e29075c24a
|
|
@ -208,10 +208,27 @@
|
|||
<li<%= sidebar_current("providers-basic-usage") %>><a href="/v2/providers/basic_usage.html">Basic Usage</a></li>
|
||||
<li<%= sidebar_current("providers-configuration") %>><a href="/v2/providers/configuration.html">Configuration</a></li>
|
||||
<li<%= sidebar_current("providers-default") %>><a href="/v2/providers/default.html">Default Provider</a></li>
|
||||
<li><a href="/v2/virtualbox/index.html">VirtualBox</a></li>
|
||||
<li><a href="/v2/vmware/index.html">VMware</a></li>
|
||||
<li><a href="/v2/docker/index.html">Docker</a></li>
|
||||
<li><a href="/v2/hyperv/index.html">Hyper-V</a></li>
|
||||
<li<%= sidebar_current("providers-custom") %>><a href="/v2/providers/custom.html">Custom Provider</a></li>
|
||||
</ul> <!-- /.sub -->
|
||||
<% end %>
|
||||
|
||||
<% if sidebar_section == "docker" %>
|
||||
<li<%= sidebar_current("docker") %>><a href="/v2/docker/index.html">Docker</a></li>
|
||||
<% if sidebar_section == "docker" %>
|
||||
<ul class="sub unstyled">
|
||||
<li<%= sidebar_current("docker-basics") %>><a href="/v2/docker/basics.html">Basic Usage</a></li>
|
||||
<li<%= sidebar_current("docker-commands") %>><a href="/v2/docker/commands.html">Commands</a></li>
|
||||
<li<%= sidebar_current("docker-boxes") %>><a href="/v2/docker/boxes.html">Boxes</a></li>
|
||||
<li<%= sidebar_current("docker-configuration") %>><a href="/v2/docker/configuration.html">Configuration</a></li>
|
||||
</ul>
|
||||
<% end %>
|
||||
<% end %>
|
||||
|
||||
<% if sidebar_section == "virtualbox" %>
|
||||
<li<%= sidebar_current("virtualbox") %>><a href="/v2/virtualbox/index.html">VirtualBox</a></li>
|
||||
<% if sidebar_section == "virtualbox" %>
|
||||
<ul class="sub unstyled">
|
||||
|
|
@ -221,7 +238,9 @@
|
|||
<li<%= sidebar_current("virtualbox-issues") %>><a href="/v2/virtualbox/common-issues.html">Common Issues</a></li>
|
||||
</ul>
|
||||
<% end %>
|
||||
<% end %>
|
||||
|
||||
<% if sidebar_section == "vmware" %>
|
||||
<li<%= sidebar_current("vmware") %>><a href="/v2/vmware/index.html">VMware</a></li>
|
||||
<% if sidebar_section == "vmware" %>
|
||||
<ul class="sub unstyled">
|
||||
|
|
@ -232,7 +251,9 @@
|
|||
<li<%= sidebar_current("vmware-known-issues") %>><a href="/v2/vmware/known-issues.html">Known Issues</a></li>
|
||||
</ul>
|
||||
<% end %>
|
||||
<% end %>
|
||||
|
||||
<% if sidebar_section == "hyperv" %>
|
||||
<li<%= sidebar_current("hyperv") %>><a href="/v2/hyperv/index.html">Hyper-V</a></li>
|
||||
<% if sidebar_section == "hyperv" %>
|
||||
<ul class="sub unstyled">
|
||||
|
|
@ -242,6 +263,7 @@
|
|||
<li<%= sidebar_current("hyperv-limitations") %>><a href="/v2/hyperv/limitations.html">Limitations</a></li>
|
||||
</ul>
|
||||
<% end %>
|
||||
<% end %>
|
||||
|
||||
<li<%= sidebar_current("plugins") %>><a href="/v2/plugins/index.html">Plugins</a></li>
|
||||
<% if sidebar_section == "plugins" %>
|
||||
|
|
|
|||
|
|
@ -0,0 +1,95 @@
|
|||
---
|
||||
page_title: "Basic Usage - Docker Provider"
|
||||
sidebar_current: "docker-basics"
|
||||
---
|
||||
|
||||
# Docker Basic Usage
|
||||
|
||||
The Docker provider in Vagrant behaves just link any other provider.
|
||||
If you're familiar with Vagrant already, then using the Docker provider
|
||||
should be intuitive and simple.
|
||||
|
||||
The Docker provider _does not_ require a `config.vm.box` setting. Since
|
||||
the "base image" for a Docker container is pulled from the
|
||||
[Docker Index](/v2/docker/images.html) or
|
||||
built from a [Dockerfile](/v2/docker/dockerfiles.html), the box doesn't
|
||||
add much value, and is optional for this provider.
|
||||
|
||||
## Docker Images
|
||||
|
||||
The first method that Vagrant can use to source a Docker container
|
||||
is via an image. This image can be from any Docker registry. An
|
||||
example is shown below:
|
||||
|
||||
<pre class="prettyprint">
|
||||
Vagrant.configure("2") do |config|
|
||||
config.vm.provider "docker" do |d|
|
||||
d.image = "foo/bar"
|
||||
end
|
||||
end
|
||||
</pre>
|
||||
|
||||
When `vagrant up --provider=docker` is run, this will bring up the
|
||||
image `foo/bar`.
|
||||
|
||||
This is useful for extra components of your application that it might
|
||||
depend on: databases, queues, etc. Typically, the primary application
|
||||
you're working on is built with a Dockerfile, or via a container with
|
||||
SSH.
|
||||
|
||||
## Dockerfiles
|
||||
|
||||
Vagrant can also automatically build and run images based on a local
|
||||
Dockerfile. This is useful for iterating on an application locally
|
||||
that is built into an image later. An example is shown below:
|
||||
|
||||
<pre class="prettyprint">
|
||||
Vagrant.configure("2") do |config|
|
||||
config.vm.provider "docker" do |d|
|
||||
d.build_dir = "."
|
||||
end
|
||||
end
|
||||
</pre>
|
||||
|
||||
The above configuration will look for a `Dockerfile` in the same
|
||||
directory as the Vagrantfile. When `vagrant up` is run, Vagrant
|
||||
automatically builds that Dockerfile and starts a container
|
||||
based on that Dockerfile.
|
||||
|
||||
The Dockerfile is rebuilt when `vagrant reload` is called.
|
||||
|
||||
## Host VM
|
||||
|
||||
On systems that can't run Linux containers natively, such as Mac OS X
|
||||
or Windows, Vagrant automatically spins up a "host VM" to run Docker.
|
||||
This allows your Docker-based Vagrant environments to remain portable,
|
||||
without inconsistencies depending on the platform they are running on.
|
||||
|
||||
Vagrant will spin up a single instance of a host VM and run multiple
|
||||
containers on this one VM. This means that with the Docker provider,
|
||||
you only have the overhead of one virtual machine, and only if it is
|
||||
absolutely necessary.
|
||||
|
||||
By default, the host VM Vagrant spins up is
|
||||
[backed by boot2docker](https://github.com/mitchellh/vagrant/blob/master/plugins/providers/docker/hostmachine/Vagrantfile),
|
||||
because it launches quickly and uses little resources. But the host VM
|
||||
can be customized to point to _any_ Vagrantfile. This allows the host VM
|
||||
to more closely match production by running a VM running Ubuntu, RHEL,
|
||||
etc. It can run any operating system supported by Vagrant.
|
||||
|
||||
An example of changing the host VM is shown below. Remember that this
|
||||
is optional, and Vagrant will spin up a default host VM if it isn't
|
||||
specified:
|
||||
|
||||
<pre class="prettyprint">
|
||||
Vagrant.configure("2") do |config|
|
||||
config.vm.provider "docker" do |d|
|
||||
d.vagrant_vagrantfile = "../path/to/Vagrantfile"
|
||||
end
|
||||
end
|
||||
</pre>
|
||||
|
||||
The host VM will be spun up at the first `vagrant up` where the provider
|
||||
is Docker. To control this host VM, use the
|
||||
[global-status command](#)
|
||||
along with global control.
|
||||
|
|
@ -0,0 +1,16 @@
|
|||
---
|
||||
page_title: "Boxes - Docker Provider"
|
||||
sidebar_current: "docker-boxes"
|
||||
---
|
||||
|
||||
# Docker Boxes
|
||||
|
||||
The Docker provider doesn't require a Vagrant box. The `config.vm.box`
|
||||
setting is completely optional.
|
||||
|
||||
A box can still be used and specified, however, to provide defaults.
|
||||
Because the `Vagrantfile` within a box is loaded as part of the
|
||||
configuration loading sequence, it can be used to configure the
|
||||
foundation of a development environment.
|
||||
|
||||
In general, however, you won't need a box with the Docker provider.
|
||||
|
|
@ -0,0 +1,30 @@
|
|||
---
|
||||
page_title: "Commands - Docker Provider"
|
||||
sidebar_current: "docker-commands"
|
||||
---
|
||||
|
||||
# Docker Commands
|
||||
|
||||
The Docker provider exposes some additional Vagrant commands that are
|
||||
useful for interacting with Docker containers. This helps with your
|
||||
workflow on top of Vagrant so that you have full access to Docker
|
||||
underneath.
|
||||
|
||||
### docker-logs
|
||||
|
||||
`vagrant docker-logs` can be used to see the logs of a running container.
|
||||
Because most Docker containers are single-process, this is used to see
|
||||
the logs of that one process. Additionally, the logs can be tailed.
|
||||
|
||||
### docker-run
|
||||
|
||||
`vagrant docker-run` can be used to run one-off commands against
|
||||
a Docker container. The one-off Docker container that is started shares
|
||||
all the volumes, links, etc. of the original Docker container. An
|
||||
example is shown below:
|
||||
|
||||
<pre class="prettyprint">
|
||||
$ vagrant docker-run app -- rake db:migrate
|
||||
</pre>
|
||||
|
||||
The above would run `rake db:migrate` in the context of an `app` container.
|
||||
|
|
@ -0,0 +1,66 @@
|
|||
---
|
||||
page_title: "Configuration- Docker Provider"
|
||||
sidebar_current: "docker-configuration"
|
||||
---
|
||||
|
||||
# Docker Configuration
|
||||
|
||||
The Docker provider has some provider-specific configuration options
|
||||
you may set. A complete reference is shown below.
|
||||
|
||||
### Required
|
||||
|
||||
* `build_dir` (string) - The path to a directory containing a Dockerfile.
|
||||
One of this or `image` is required.
|
||||
|
||||
* `image` (string) - The image to launch, specified by the image ID or a name
|
||||
such as `ubuntu:12.04`. One of this or `build_dir` is required.
|
||||
|
||||
### Optional
|
||||
|
||||
* `cmd` (array of strings) - Custom command to run on the container.
|
||||
Example: `["ls", "/app"]`.
|
||||
|
||||
* `create_args` (array of strings) - Additional arguments to pass to
|
||||
`docker run` when the container is started. This can be used to set
|
||||
parameters that aren't exposed via the Vagrantfile.
|
||||
|
||||
* `env` (hash) - Environmental variables to expose into the container.
|
||||
|
||||
* `expose` (array of integers) - Ports to expose from the container
|
||||
but not to the host machine. Useful for links.
|
||||
|
||||
* `link` (method, string argument) - Link this container to another
|
||||
by name. Example: `docker.link("db")`.
|
||||
|
||||
* `force_host_vm` (boolean) - If true, then a host VM will be spun up
|
||||
even if the computer running Vagrant supports Linux containers. This
|
||||
is useful to enforce a consistent environment to run Docker.
|
||||
|
||||
* `has_ssh` (boolean) - If true, then Vagrant will support SSH with
|
||||
the container. This allows `vagrant ssh` to work, provisioners, etc.
|
||||
This defaults to false.
|
||||
|
||||
* `name` (string) - Name of the container. Note that this has to be unique
|
||||
across all containers on the host VM. By default Vagrant will generate
|
||||
some random name.
|
||||
|
||||
* `ports` (array of strings) - Ports to expose from the container to the
|
||||
host. These should be in the format of `host:container`.
|
||||
|
||||
* `remains_running` (boolean) - If true, Vagrant expects this container
|
||||
to remain running and will make sure that it does for a certain amount
|
||||
of time. If false, then Vagrant expects that this container will
|
||||
automatically stop at some point, and won't error if it sees it do that.
|
||||
|
||||
* `vagrant_machine` (string) - The name of the Vagrant machine in the
|
||||
`vagrant_vagrantfile` to use as the host machine. This defaults to
|
||||
"default".
|
||||
|
||||
* `vagrant_vagrantfile` (string) - Path to a Vagrantfile that contains
|
||||
the `vagrant_machine` to use as the host VM if needed.
|
||||
|
||||
* `volumes` (array of strings) - List of directories to mount as
|
||||
volumes into the container. These directories must exist in the
|
||||
host where Docker is running. If you want to sync folders from the
|
||||
host Vagrant is running, just use synced folders.
|
||||
|
|
@ -0,0 +1,23 @@
|
|||
---
|
||||
page_title: "Docker Provider"
|
||||
sidebar_current: "docker"
|
||||
---
|
||||
|
||||
# Docker
|
||||
|
||||
Vagrant comes with support out of the box for
|
||||
using Docker as a provider. This allows for your development environments
|
||||
to be backed by Docker containers rather than virtual machines. Additionally,
|
||||
it provides for a good workflow for developing Dockerfiles.
|
||||
|
||||
<div class="alert alert-warn">
|
||||
<p>
|
||||
<strong>Warning: Docker knowledge assumed.</strong> We assume that
|
||||
you know what Docker is and that you're comfortable with the basics
|
||||
of Docker. If not, we recommend starting with another provider such
|
||||
as <a href="/v2/virtualbox/index.html">VirtualBox</a>.
|
||||
</p>
|
||||
</div>
|
||||
|
||||
Use the navigation to the left to find a specific Docker topic
|
||||
to read more about.
|
||||
Loading…
Reference in New Issue