mirror of https://github.com/docker/compose.git
Merge pull request #855 from SvenDowideit/add-docker-docs-metadata-and-reflow-to-80-chars
Add Docker docs.docker.com meta-data, and reflow to 80-chars to simplify GH diffs
This commit is contained in:
Fred Lifton
commit
2307adc4b2
63
docs/cli.md
63
docs/cli.md
|
|
@ -1,12 +1,15 @@
|
|||
---
|
||||
layout: default
|
||||
title: Compose CLI reference
|
||||
page_title: Compose CLI reference
|
||||
page_description: Compose CLI reference
|
||||
page_keywords: fig, composition, compose, docker
|
||||
---
|
||||
|
||||
CLI reference
|
||||
=============
|
||||
# CLI reference
|
||||
|
||||
Most commands are run against one or more services. If the service is omitted, it will apply to all services.
|
||||
Most commands are run against one or more services. If the service is omitted,
|
||||
it will apply to all services.
|
||||
|
||||
Run `docker-compose [COMMAND] --help` for full usage.
|
||||
|
||||
|
|
@ -34,7 +37,9 @@ Run `docker-compose [COMMAND] --help` for full usage.
|
|||
|
||||
Build or rebuild services.
|
||||
|
||||
Services are built once and then tagged as `project_service`, e.g. `composetest_db`. If you change a service's `Dockerfile` or the contents of its build directory, you can run `docker-compose build` to rebuild it.
|
||||
Services are built once and then tagged as `project_service`, e.g.,`composetest_db`.
|
||||
If you change a service's `Dockerfile` or the contents of its build directory, you
|
||||
can run `docker-compose build` to rebuild it.
|
||||
|
||||
### help
|
||||
|
||||
|
|
@ -42,7 +47,8 @@ Get help on a command.
|
|||
|
||||
### kill
|
||||
|
||||
Force stop running containers by sending a `SIGKILL` signal. Optionally the signal can be passed, for example:
|
||||
Force stop running containers by sending a `SIGKILL` signal. Optionally the signal
|
||||
can be passed, for example:
|
||||
|
||||
$ docker-compose kill -s SIGINT
|
||||
|
||||
|
|
@ -77,17 +83,24 @@ For example:
|
|||
|
||||
By default, linked services will be started, unless they are already running.
|
||||
|
||||
One-off commands are started in new containers with the same configuration as a normal container for that service, so volumes, links, etc will all be created as expected. The only thing different to a normal container is the command will be overridden with the one specified and by default no ports will be created in case they collide.
|
||||
One-off commands are started in new containers with the same configuration as a
|
||||
normal container for that service, so volumes, links, etc will all be created as
|
||||
expected. The only thing different to a normal container is the command will be
|
||||
overridden with the one specified and by default no ports will be created in case
|
||||
they collide.
|
||||
|
||||
Links are also created between one-off commands and the other containers for that service so you can do stuff like this:
|
||||
Links are also created between one-off commands and the other containers for that
|
||||
service so you can do stuff like this:
|
||||
|
||||
$ docker-compose run db psql -h db -U docker
|
||||
|
||||
If you do not want linked containers to be started when running the one-off command, specify the `--no-deps` flag:
|
||||
If you do not want linked containers to be started when running the one-off command,
|
||||
specify the `--no-deps` flag:
|
||||
|
||||
$ docker-compose run --no-deps web python manage.py shell
|
||||
|
||||
If you want the service's ports to be created and mapped to the host, specify the `--service-ports` flag:
|
||||
If you want the service's ports to be created and mapped to the host, specify the
|
||||
`--service-ports` flag:
|
||||
$ docker-compose run --service-ports web python manage.py shell
|
||||
|
||||
### scale
|
||||
|
|
@ -105,7 +118,8 @@ Start existing containers for a service.
|
|||
|
||||
### stop
|
||||
|
||||
Stop running containers without removing them. They can be started again with `docker-compose start`.
|
||||
Stop running containers without removing them. They can be started again with
|
||||
`docker-compose start`.
|
||||
|
||||
### up
|
||||
|
||||
|
|
@ -113,9 +127,15 @@ Build, (re)create, start and attach to containers for a service.
|
|||
|
||||
Linked services will be started, unless they are already running.
|
||||
|
||||
By default, `docker-compose up` will aggregate the output of each container, and when it exits, all containers will be stopped. If you run `docker-compose up -d`, it'll start the containers in the background and leave them running.
|
||||
By default, `docker-compose up` will aggregate the output of each container, and when
|
||||
it exits, all containers will be stopped. If you run `docker-compose up -d`, it'll
|
||||
start the containers in the background and leave them running.
|
||||
|
||||
By default if there are existing containers for a service, `docker-compose up` will stop and recreate them (preserving mounted volumes with [volumes-from]), so that changes in `docker-compose.yml` are picked up. If you do no want containers to be stopped and recreated, use `docker-compose up --no-recreate`. This will still start any stopped containers, if needed.
|
||||
By default if there are existing containers for a service, `docker-compose up` will
|
||||
stop and recreate them (preserving mounted volumes with [volumes-from]), so that
|
||||
changes in `docker-compose.yml` are picked up. If you do not want containers to be
|
||||
stopped and recreated, use `docker-compose up --no-recreate`. This will still start
|
||||
any stopped containers, if needed.
|
||||
|
||||
[volumes-from]: http://docs.docker.io/en/latest/use/working_with_volumes/
|
||||
|
||||
|
|
@ -124,24 +144,31 @@ By default if there are existing containers for a service, `docker-compose up` w
|
|||
|
||||
Several environment variables can be used to configure Compose's behaviour.
|
||||
|
||||
Variables starting with `DOCKER_` are the same as those used to configure the Docker command-line client. If you're using boot2docker, `$(boot2docker shellinit)` will set them to their correct values.
|
||||
Variables starting with `DOCKER_` are the same as those used to configure the
|
||||
Docker command-line client. If you're using boot2docker, `$(boot2docker shellinit)`
|
||||
will set them to their correct values.
|
||||
|
||||
### FIG\_PROJECT\_NAME
|
||||
|
||||
Set the project name, which is prepended to the name of every container started by Compose. Defaults to the `basename` of the current working directory.
|
||||
Set the project name, which is prepended to the name of every container started by
|
||||
Compose. Defaults to the `basename` of the current working directory.
|
||||
|
||||
### FIG\_FILE
|
||||
|
||||
Set the path to the `docker-compose.yml` to use. Defaults to `docker-compose.yml` in the current working directory.
|
||||
Set the path to the `docker-compose.yml` to use. Defaults to `docker-compose.yml`
|
||||
in the current working directory.
|
||||
|
||||
### DOCKER\_HOST
|
||||
|
||||
Set the URL to the docker daemon. Defaults to `unix:///var/run/docker.sock`, as with the docker client.
|
||||
Set the URL to the docker daemon. Defaults to `unix:///var/run/docker.sock`, as
|
||||
with the docker client.
|
||||
|
||||
### DOCKER\_TLS\_VERIFY
|
||||
|
||||
When set to anything other than an empty string, enables TLS communication with the daemon.
|
||||
When set to anything other than an empty string, enables TLS communication with
|
||||
the daemon.
|
||||
|
||||
### DOCKER\_CERT\_PATH
|
||||
|
||||
Configure the path to the `ca.pem`, `cert.pem` and `key.pem` files used for TLS verification. Defaults to `~/.docker`.
|
||||
Configure the path to the `ca.pem`, `cert.pem` and `key.pem` files used for TLS
|
||||
verification. Defaults to `~/.docker`.
|
||||
|
|
|
|||
|
|
@ -1,8 +1,13 @@
|
|||
---
|
||||
layout: default
|
||||
title: Compose: Multi-container orchestration for Docker
|
||||
page_title: Compose: Multi-container orchestration for Docker
|
||||
page_description: Compose: Multi-container orchestration for Docker
|
||||
page_keywords: fig, composition, compose, docker
|
||||
---
|
||||
|
||||
# <strong class="strapline">Fast, isolated development environments using Docker.</strong>
|
||||
|
||||
Define your app's environment with a `Dockerfile` so it can be reproduced anywhere:
|
||||
|
||||
FROM python:2.7
|
||||
|
|
@ -10,7 +15,8 @@ Define your app's environment with a `Dockerfile` so it can be reproduced anywhe
|
|||
WORKDIR /code
|
||||
RUN pip install -r requirements.txt
|
||||
|
||||
Define the services that make up your app in `docker-compose.yml` so they can be run together in an isolated environment:
|
||||
Define the services that make up your app in `docker-compose.yml` so they can be
|
||||
run together in an isolated environment:
|
||||
|
||||
```yaml
|
||||
web:
|
||||
|
|
@ -36,10 +42,10 @@ There are commands to:
|
|||
- run a one-off command on a service
|
||||
|
||||
|
||||
Quick start
|
||||
-----------
|
||||
## Quick start
|
||||
|
||||
Let's get a basic Python web app running on Compose. It assumes a little knowledge of Python, but the concepts should be clear if you're not familiar with it.
|
||||
Let's get a basic Python web app running on Compose. It assumes a little knowledge
|
||||
of Python, but the concepts should be clear if you're not familiar with it.
|
||||
|
||||
First, [install Docker and Compose](install.html).
|
||||
|
||||
|
|
@ -48,7 +54,8 @@ You'll want to make a directory for the project:
|
|||
$ mkdir composetest
|
||||
$ cd composetest
|
||||
|
||||
Inside this directory, create `app.py`, a simple web app that uses the Flask framework and increments a value in Redis:
|
||||
Inside this directory, create `app.py`, a simple web app that uses the Flask
|
||||
framework and increments a value in Redis:
|
||||
|
||||
```python
|
||||
from flask import Flask
|
||||
|
|
@ -71,14 +78,18 @@ We define our Python dependencies in a file called `requirements.txt`:
|
|||
flask
|
||||
redis
|
||||
|
||||
Next, we want to create a Docker image containing all of our app's dependencies. We specify how to build one using a file called `Dockerfile`:
|
||||
Next, we want to create a Docker image containing all of our app's dependencies.
|
||||
We specify how to build one using a file called `Dockerfile`:
|
||||
|
||||
FROM python:2.7
|
||||
ADD . /code
|
||||
WORKDIR /code
|
||||
RUN pip install -r requirements.txt
|
||||
|
||||
This tells Docker to install Python, our code and our Python dependencies inside a Docker image. For more information on how to write Dockerfiles, see the [Docker user guide](https://docs.docker.com/userguide/dockerimages/#building-an-image-from-a-dockerfile) and the [Dockerfile reference](http://docs.docker.com/reference/builder/).
|
||||
This tells Docker to install Python, our code and our Python dependencies inside
|
||||
a Docker image. For more information on how to write Dockerfiles, see the
|
||||
[Docker user guide](https://docs.docker.com/userguide/dockerimages/#building-an-image-from-a-dockerfile)
|
||||
and the [Dockerfile reference](http://docs.docker.com/reference/builder/).
|
||||
|
||||
We then define a set of services using `docker-compose.yml`:
|
||||
|
||||
|
|
@ -96,7 +107,11 @@ We then define a set of services using `docker-compose.yml`:
|
|||
|
||||
This defines two services:
|
||||
|
||||
- `web`, which is built from `Dockerfile` in the current directory. It also says to run the command `python app.py` inside the image, forward the exposed port 5000 on the container to port 5000 on the host machine, connect up the Redis service, and mount the current directory inside the container so we can work on code without having to rebuild the image.
|
||||
- `web`, which is built from `Dockerfile` in the current directory. It also says
|
||||
to run the command `python app.py` inside the image, forward the exposed port
|
||||
5000 on the container to port 5000 on the host machine, connect up the Redis
|
||||
service, and mount the current directory inside the container so we can work
|
||||
on code without having to rebuild the image.
|
||||
- `redis`, which uses the public image [redis](https://registry.hub.docker.com/_/redis/).
|
||||
|
||||
Now if we run `docker-compose up`, it'll pull a Redis image, build an image for our own code, and start everything up:
|
||||
|
|
@ -109,9 +124,11 @@ Now if we run `docker-compose up`, it'll pull a Redis image, build an image for
|
|||
redis_1 | [8] 02 Jan 18:43:35.576 # Server started, Redis version 2.8.3
|
||||
web_1 | * Running on http://0.0.0.0:5000/
|
||||
|
||||
The web app should now be listening on port 5000 on your docker daemon (if you're using boot2docker, `boot2docker ip` will tell you its address).
|
||||
The web app should now be listening on port 5000 on your docker daemon (if you're
|
||||
using boot2docker, `boot2docker ip` will tell you its address).
|
||||
|
||||
If you want to run your services in the background, you can pass the `-d` flag to `docker-compose up` and use `docker-compose ps` to see what is currently running:
|
||||
If you want to run your services in the background, you can pass the `-d` flag to
|
||||
`docker-compose up` and use `docker-compose ps` to see what is currently running:
|
||||
|
||||
$ docker-compose up -d
|
||||
Starting composetest_redis_1...
|
||||
|
|
@ -122,15 +139,19 @@ If you want to run your services in the background, you can pass the `-d` flag t
|
|||
composetest_redis_1 /usr/local/bin/run Up
|
||||
composetest_web_1 /bin/sh -c python app.py Up 5000->5000/tcp
|
||||
|
||||
`docker-compose run` allows you to run one-off commands for your services. For example, to see what environment variables are available to the `web` service:
|
||||
`docker-compose run` allows you to run one-off commands for your services. For
|
||||
example, to see what environment variables are available to the `web` service:
|
||||
|
||||
$ docker-compose run web env
|
||||
|
||||
|
||||
See `docker-compose --help` other commands that are available.
|
||||
|
||||
If you started Compose with `docker-compose up -d`, you'll probably want to stop your services once you've finished with them:
|
||||
If you started Compose with `docker-compose up -d`, you'll probably want to stop
|
||||
your services once you've finished with them:
|
||||
|
||||
$ docker-compose stop
|
||||
|
||||
That's more-or-less how Compose works. See the reference section below for full details on the commands, configuration file and environment variables. If you have any thoughts or suggestions, [open an issue on GitHub](https://github.com/docker/docker-compose).
|
||||
That's more-or-less how Compose works. See the reference section below for full
|
||||
details on the commands, configuration file and environment variables. If you
|
||||
have any thoughts or suggestions, [open an issue on GitHub](https://github.com/docker/docker-compose).
|
||||
|
|
|
|||
|
|
@ -1,20 +1,26 @@
|
|||
---
|
||||
layout: default
|
||||
title: Installing Compose
|
||||
page_title: Installing Compose
|
||||
page_description: Installing Compose
|
||||
page_keywords: fig, composition, compose, docker
|
||||
---
|
||||
|
||||
Installing Compose
|
||||
==============
|
||||
# Installing Compose
|
||||
|
||||
First, install Docker version 1.3 or greater.
|
||||
|
||||
If you're on OS X, you can use the [OS X installer](https://docs.docker.com/installation/mac/) to install both Docker and boot2docker. Once boot2docker is running, set the environment variables that'll configure Docker and Compose to talk to it:
|
||||
If you're on OS X, you can use the [OS X installer](https://docs.docker.com/installation/mac/)
|
||||
to install both Docker and boot2docker. Once boot2docker is running, set the environment
|
||||
variables that'll configure Docker and Compose to talk to it:
|
||||
|
||||
$(boot2docker shellinit)
|
||||
|
||||
To persist the environment variables across shell sessions, you can add that line to your `~/.bashrc` file.
|
||||
To persist the environment variables across shell sessions, you can add that line
|
||||
to your `~/.bashrc` file.
|
||||
|
||||
There are also guides for [Ubuntu](https://docs.docker.com/installation/ubuntulinux/) and [other platforms](https://docs.docker.com/installation/) in Docker’s documentation.
|
||||
There are also guides for [Ubuntu](https://docs.docker.com/installation/ubuntulinux/)
|
||||
and [other platforms](https://docs.docker.com/installation/) in Docker`s documentation.
|
||||
|
||||
Next, install Compose:
|
||||
|
||||
|
|
@ -22,7 +28,8 @@ Next, install Compose:
|
|||
|
||||
Optionally, install [command completion](completion.html) for the bash shell.
|
||||
|
||||
Releases are available for OS X and 64-bit Linux. Compose is also available as a Python package if you're on another platform (or if you prefer that sort of thing):
|
||||
Releases are available for OS X and 64-bit Linux. Compose is also available as a Python
|
||||
package if you're on another platform (or if you prefer that sort of thing):
|
||||
|
||||
$ sudo pip install -U docker-compose
|
||||
|
||||
|
|
|
|||
55
docs/yml.md
55
docs/yml.md
|
|
@ -1,18 +1,25 @@
|
|||
---
|
||||
layout: default
|
||||
title: docker-compose.yml reference
|
||||
page_title: docker-compose.yml reference
|
||||
page_description: docker-compose.yml reference
|
||||
page_keywords: fig, composition, compose, docker
|
||||
---
|
||||
|
||||
docker-compose.yml reference
|
||||
=================
|
||||
# docker-compose.yml reference
|
||||
|
||||
Each service defined in `docker-compose.yml` must specify exactly one of `image` or `build`. Other keys are optional, and are analogous to their `docker run` command-line counterparts.
|
||||
Each service defined in `docker-compose.yml` must specify exactly one of
|
||||
`image` or `build`. Other keys are optional, and are analogous to their
|
||||
`docker run` command-line counterparts.
|
||||
|
||||
As with `docker run`, options specified in the Dockerfile (e.g. `CMD`, `EXPOSE`, `VOLUME`, `ENV`) are respected by default - you don't need to specify them again in `docker-compose.yml`.
|
||||
As with `docker run`, options specified in the Dockerfile (e.g., `CMD`,
|
||||
`EXPOSE`, `VOLUME`, `ENV`) are respected by default - you don't need to
|
||||
specify them again in `docker-compose.yml`.
|
||||
|
||||
###image
|
||||
### image
|
||||
|
||||
Tag or partial image ID. Can be local or remote - Compose will attempt to pull if it doesn't exist locally.
|
||||
Tag or partial image ID. Can be local or remote - Compose will attempt to
|
||||
pull if it doesn't exist locally.
|
||||
|
||||
```
|
||||
image: ubuntu
|
||||
|
|
@ -22,7 +29,8 @@ image: a4bc65fd
|
|||
|
||||
### build
|
||||
|
||||
Path to a directory containing a Dockerfile. Compose will build and tag it with a generated name, and use that image thereafter.
|
||||
Path to a directory containing a Dockerfile. Compose will build and tag it
|
||||
with a generated name, and use that image thereafter.
|
||||
|
||||
```
|
||||
build: /path/to/build/dir
|
||||
|
|
@ -39,7 +47,9 @@ command: bundle exec thin -p 3000
|
|||
<a name="links"></a>
|
||||
### links
|
||||
|
||||
Link to containers in another service. Either specify both the service name and the link alias (`SERVICE:ALIAS`), or just the service name (which will also be used for the alias).
|
||||
Link to containers in another service. Either specify both the service name and
|
||||
the link alias (`SERVICE:ALIAS`), or just the service name (which will also be
|
||||
used for the alias).
|
||||
|
||||
```
|
||||
links:
|
||||
|
|
@ -48,7 +58,8 @@ links:
|
|||
- redis
|
||||
```
|
||||
|
||||
An entry with the alias' name will be created in `/etc/hosts` inside containers for this service, e.g:
|
||||
An entry with the alias' name will be created in `/etc/hosts` inside containers
|
||||
for this service, e.g:
|
||||
|
||||
```
|
||||
172.17.2.186 db
|
||||
|
|
@ -56,12 +67,15 @@ An entry with the alias' name will be created in `/etc/hosts` inside containers
|
|||
172.17.2.187 redis
|
||||
```
|
||||
|
||||
Environment variables will also be created - see the [environment variable reference](env.html) for details.
|
||||
Environment variables will also be created - see the [environment variable
|
||||
reference](env.html) for details.
|
||||
|
||||
### external_links
|
||||
|
||||
Link to containers started outside this `docker-compose.yml` or even outside of Compose, especially for containers that provide shared or common services.
|
||||
`external_links` follow semantics similar to `links` when specifying both the container name and the link alias (`CONTAINER:ALIAS`).
|
||||
Link to containers started outside this `docker-compose.yml` or even outside
|
||||
of Compose, especially for containers that provide shared or common services.
|
||||
`external_links` follow semantics similar to `links` when specifying both the
|
||||
container name and the link alias (`CONTAINER:ALIAS`).
|
||||
|
||||
```
|
||||
external_links:
|
||||
|
|
@ -72,9 +86,13 @@ external_links:
|
|||
|
||||
### ports
|
||||
|
||||
Expose ports. Either specify both ports (`HOST:CONTAINER`), or just the container port (a random host port will be chosen).
|
||||
Expose ports. Either specify both ports (`HOST:CONTAINER`), or just the container
|
||||
port (a random host port will be chosen).
|
||||
|
||||
**Note:** When mapping ports in the `HOST:CONTAINER` format, you may experience erroneous results when using a container port lower than 60, because YAML will parse numbers in the format `xx:yy` as sexagesimal (base 60). For this reason, we recommend always explicitly specifying your port mappings as strings.
|
||||
> **Note:** When mapping ports in the `HOST:CONTAINER` format, you may experience
|
||||
> erroneous results when using a container port lower than 60, because YAML will
|
||||
> parse numbers in the format `xx:yy` as sexagesimal (base 60). For this reason,
|
||||
> we recommend always explicitly specifying your port mappings as strings.
|
||||
|
||||
```
|
||||
ports:
|
||||
|
|
@ -86,7 +104,8 @@ ports:
|
|||
|
||||
### expose
|
||||
|
||||
Expose ports without publishing them to the host machine - they'll only be accessible to linked services. Only the internal port can be specified.
|
||||
Expose ports without publishing them to the host machine - they'll only be
|
||||
accessible to linked services. Only the internal port can be specified.
|
||||
|
||||
```
|
||||
expose:
|
||||
|
|
@ -120,7 +139,8 @@ volumes_from:
|
|||
|
||||
Add environment variables. You can use either an array or a dictionary.
|
||||
|
||||
Environment variables with only a key are resolved to their values on the machine Compose is running on, which can be helpful for secret or host-specific values.
|
||||
Environment variables with only a key are resolved to their values on the
|
||||
machine Compose is running on, which can be helpful for secret or host-specific values.
|
||||
|
||||
```
|
||||
environment:
|
||||
|
|
@ -196,7 +216,8 @@ dns_search:
|
|||
|
||||
### working\_dir, entrypoint, user, hostname, domainname, mem\_limit, privileged, restart, stdin\_open, tty, cpu\_shares
|
||||
|
||||
Each of these is a single value, analogous to its [docker run](https://docs.docker.com/reference/run/) counterpart.
|
||||
Each of these is a single value, analogous to its
|
||||
[docker run](https://docs.docker.com/reference/run/) counterpart.
|
||||
|
||||
```
|
||||
cpu_shares: 73
|
||||
|
|
|
|||
Loading…
Reference in New Issue