From e29075c24af935c863f7fa93b8bd62fb0d1d8cf3 Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Wed, 30 Apr 2014 18:43:01 -0700 Subject: [PATCH] website/docs: docker provider --- website/docs/source/layouts/layout.erb | 22 +++++ website/docs/source/v2/docker/basics.html.md | 95 +++++++++++++++++++ website/docs/source/v2/docker/boxes.html.md | 16 ++++ .../docs/source/v2/docker/commands.html.md | 30 ++++++ .../source/v2/docker/configuration.html.md | 66 +++++++++++++ website/docs/source/v2/docker/index.html.md | 23 +++++ 6 files changed, 252 insertions(+) create mode 100644 website/docs/source/v2/docker/basics.html.md create mode 100644 website/docs/source/v2/docker/boxes.html.md create mode 100644 website/docs/source/v2/docker/commands.html.md create mode 100644 website/docs/source/v2/docker/configuration.html.md create mode 100644 website/docs/source/v2/docker/index.html.md diff --git a/website/docs/source/layouts/layout.erb b/website/docs/source/layouts/layout.erb index 74265d570..493081ef1 100644 --- a/website/docs/source/layouts/layout.erb +++ b/website/docs/source/layouts/layout.erb @@ -208,10 +208,27 @@ >Basic Usage >Configuration >Default Provider +
  • VirtualBox
    • +
  • VMware
    • +
  • Docker
    • +
  • Hyper-V
    • >Custom Provider <% end %> + <% if sidebar_section == "docker" %> + >Docker + <% if sidebar_section == "docker" %> + + <% end %> + <% end %> + + <% if sidebar_section == "virtualbox" %> >VirtualBox <% if sidebar_section == "virtualbox" %> <% end %> + <% end %> + <% if sidebar_section == "vmware" %> >VMware <% if sidebar_section == "vmware" %> <% end %> + <% end %> + <% if sidebar_section == "hyperv" %> >Hyper-V <% if sidebar_section == "hyperv" %> <% end %> + <% end %> >Plugins <% if sidebar_section == "plugins" %> diff --git a/website/docs/source/v2/docker/basics.html.md b/website/docs/source/v2/docker/basics.html.md new file mode 100644 index 000000000..7901ad548 --- /dev/null +++ b/website/docs/source/v2/docker/basics.html.md @@ -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: + +
    +Vagrant.configure("2") do |config|
+  config.vm.provider "docker" do |d|
+    d.image = "foo/bar"
+  end
+end
+
    + +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: + +
    +Vagrant.configure("2") do |config|
+  config.vm.provider "docker" do |d|
+    d.build_dir = "."
+  end
+end
+
    + +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: + +
    +Vagrant.configure("2") do |config|
+  config.vm.provider "docker" do |d|
+    d.vagrant_vagrantfile = "../path/to/Vagrantfile"
+  end
+end
+
    + +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. diff --git a/website/docs/source/v2/docker/boxes.html.md b/website/docs/source/v2/docker/boxes.html.md new file mode 100644 index 000000000..7ecc72d99 --- /dev/null +++ b/website/docs/source/v2/docker/boxes.html.md @@ -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. diff --git a/website/docs/source/v2/docker/commands.html.md b/website/docs/source/v2/docker/commands.html.md new file mode 100644 index 000000000..b77d3c2fe --- /dev/null +++ b/website/docs/source/v2/docker/commands.html.md @@ -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: + +
    +$ vagrant docker-run app -- rake db:migrate
+
    + +The above would run `rake db:migrate` in the context of an `app` container. diff --git a/website/docs/source/v2/docker/configuration.html.md b/website/docs/source/v2/docker/configuration.html.md new file mode 100644 index 000000000..b2c146bac --- /dev/null +++ b/website/docs/source/v2/docker/configuration.html.md @@ -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. diff --git a/website/docs/source/v2/docker/index.html.md b/website/docs/source/v2/docker/index.html.md new file mode 100644 index 000000000..694b5990c --- /dev/null +++ b/website/docs/source/v2/docker/index.html.md @@ -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. + +
    +

    + Warning: Docker knowledge assumed. 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 VirtualBox. +

    +
    + +Use the navigation to the left to find a specific Docker topic +to read more about.