Merge pull request #3452 from SvenDowideit/cherry-pick-v1.7.1-docs-fixes

Cherry pick v1.7.1 docs fixes

compose/cli/main.py

@@ -265,18 +265,29 @@ class TopLevelCommand(object):
 
     def down(self, options):
         """
-        Stop containers and remove containers, networks, volumes, and images
+        Stops containers and removes containers, networks, volumes, and images
-        created by `up`. Only containers and networks are removed by default.
+        created by `up`.
+
+        By default, the only things removed are:
+
+        - Containers for services defined in the Compose file
+        - Networks defined in the `networks` section of the Compose file
+        - The default network, if one is used
+
+        Networks and volumes defined as `external` are never removed.
 
         Usage: down [options]
 
         Options:
-            --rmi type          Remove images, type may be one of: 'all' to remove
+            --rmi type          Remove images. Type must be one of:
-                                all images, or 'local' to remove only images that
+                                'all': Remove all images used by any service.
-                                don't have an custom name set by the `image` field
+                                'local': Remove only images that don't have a custom tag
-            -v, --volumes       Remove data volumes
+                                set by the `image` field.
-            --remove-orphans    Remove containers for services not defined in
+            -v, --volumes       Remove named volumes declared in the `volumes` section
-                                the Compose file
+                                of the Compose file and anonymous volumes
+                                attached to containers.
+            --remove-orphans    Remove containers for services not defined in the
+                                Compose file
         """
         image_type = image_type_from_opt('--rmi', options['--rmi'])
         self.project.down(image_type, options['--volumes'], options['--remove-orphans'])
@@ -502,10 +513,10 @@ class TopLevelCommand(object):
 
     def rm(self, options):
         """
-        Remove stopped service containers.
+        Removes stopped service containers.
 
-        By default, volumes attached to containers will not be removed. You can see all
+        By default, anonymous volumes attached to containers will not be removed. You
-        volumes with `docker volume ls`.
+        can override this with `-v`. To list all volumes, use `docker volume ls`.
 
         Any data which is not in a volume will be lost.
 
@@ -513,7 +524,7 @@ class TopLevelCommand(object):
 
         Options:
             -f, --force   Don't ask to confirm removal
-            -v            Remove volumes associated with containers
+            -v            Remove any anonymous volumes attached to containers
             -a, --all     Also remove one-off containers created by
                           docker-compose run
         """

docs/Dockerfile

@@ -1,18 +1,8 @@
-FROM docs/base:latest
+FROM docs/base:oss
 MAINTAINER Mary Anthony <mary@docker.com> (@moxiegirl)
 
-RUN svn checkout https://github.com/docker/docker/trunk/docs /docs/content/engine
-RUN svn checkout https://github.com/docker/swarm/trunk/docs /docs/content/swarm
-RUN svn checkout https://github.com/docker/machine/trunk/docs /docs/content/machine
-RUN svn checkout https://github.com/docker/distribution/trunk/docs /docs/content/registry
-RUN svn checkout https://github.com/docker/notary/trunk/docs /docs/content/notary
-RUN svn checkout https://github.com/docker/kitematic/trunk/docs /docs/content/kitematic
-RUN svn checkout https://github.com/docker/toolbox/trunk/docs /docs/content/toolbox
-RUN svn checkout https://github.com/docker/opensource/trunk/docs /docs/content/project
-
-
 ENV PROJECT=compose
 # To get the git info for this repo
 COPY . /src
-
+RUN rm -r /docs/content/$PROJECT/
 COPY . /docs/content/$PROJECT/

docs/compose-file.md

@@ -59,13 +59,13 @@ optionally [dockerfile](#dockerfile) and [args](#args).
       args:
         buildno: 1
 
-If you specify `image` as well as `build`, then Compose tags the built image
+If you specify `image` as well as `build`, then Compose names the built image
-with the tag specified in `image`:
+with the `webapp` and optional `tag` specified in `image`:
 
     build: ./dir
-    image: webapp
+    image: webapp:tag
 
-This will result in an image tagged `webapp`, built from `./dir`.
+This will result in an image named `webapp` and tagged `tag`, built from `./dir`.
 
 > **Note**: In the [version 1 file format](#version-1), `build` is different in
 > two ways:
@@ -502,9 +502,11 @@ the special form `service:[service name]`.
 Networks to join, referencing entries under the
 [top-level `networks` key](#network-configuration-reference).
 
-    networks:
+    services:
-      - some-network
+      some-service:
-      - other-network
+        networks:
+         - some-network
+         - other-network
 
 #### aliases
 
@@ -516,14 +518,16 @@ Since `aliases` is network-scoped, the same service can have different aliases o
 
 The general format is shown here.
 
-    networks:
+    services:
-      some-network:
+      some-service:
-        aliases:
+        networks:
-          - alias1
+          some-network:
-          - alias3
+            aliases:
-      other-network:
+             - alias1
-        aliases:
+             - alias3
-          - alias2
+          other-network:
+            aliases:
+             - alias2
 
 In the example below, three services are provided (`web`, `worker`, and `db`), along with two networks (`new` and `legacy`). The `db` service is reachable at the hostname `db` or `database` on the `new` network, and at `db` or `mysql` on the `legacy` network.
 
@@ -1079,7 +1083,7 @@ It's more complicated if you're using particular configuration features:
           data: {}
 
     By default, Compose creates a volume whose name is prefixed with your
-    project name. If you want it to just be called `data`, declared it as
+    project name. If you want it to just be called `data`, declare it as
     external:
 
         volumes:
@@ -1089,21 +1093,24 @@ It's more complicated if you're using particular configuration features:
 ## Variable substitution
 
 Your configuration options can contain environment variables. Compose uses the
-variable values from the shell environment in which `docker-compose` is run. For
+variable values from the shell environment in which `docker-compose` is run.
-example, suppose the shell contains `POSTGRES_VERSION=9.3` and you supply this
+For example, suppose the shell contains `EXTERNAL_PORT=8000` and you supply
-configuration:
+this configuration:
 
-    db:
+    web:
-      image: "postgres:${POSTGRES_VERSION}"
+      build: .
+      ports:
+        - "${EXTERNAL_PORT}:5000"
 
-When you run `docker-compose up` with this configuration, Compose looks for the
+When you run `docker-compose up` with this configuration, Compose looks for
-`POSTGRES_VERSION` environment variable in the shell and substitutes its value
+the `EXTERNAL_PORT` environment variable in the shell and substitutes its
-in. For this example, Compose resolves the `image` to `postgres:9.3` before
+value in. In this example, Compose resolves the port mapping to `"8000:5000"`
-running the configuration.
+before creating the `web` container.
 
 If an environment variable is not set, Compose substitutes with an empty
-string. In the example above, if `POSTGRES_VERSION` is not set, the value for
+string. In the example above, if `EXTERNAL_PORT` is not set, the value for the
-the `image` option is `postgres:`.
+port mapping is `:5000` (which is of course an invalid port mapping, and will
+result in an error when attempting to create the container).
 
 Both `$VARIABLE` and `${VARIABLE}` syntax are supported. Extended shell-style
 features, such as `${VARIABLE-default}` and `${VARIABLE/foo/bar}`, are not

docs/django.md

@@ -15,7 +15,7 @@ weight=4
 This quick-start guide demonstrates how to use Docker Compose to set up and run a simple Django/PostgreSQL app. Before starting, you'll need to have
 [Compose installed](install.md).
 
-## Define the project components
+### Define the project components
 
 For this project, you need to create a Dockerfile, a Python dependencies file,
 and a `docker-compose.yml` file.
@@ -89,7 +89,7 @@ and a `docker-compose.yml` file.
 
 10. Save and close the `docker-compose.yml` file.
 
-## Create a Django project
+### Create a Django project
 
 In this step, you create a Django started project by building the image from the build context defined in the previous procedure.
 
@@ -137,7 +137,7 @@ In this step, you create a Django started project by building the image from the
         -rw-r--r--  1 user  staff   16 Feb 13 23:01 requirements.txt
 
 
-## Connect the database
+### Connect the database
 
 In this section, you set up the database connection for Django.
 

docs/rails.md

@@ -22,7 +22,7 @@ container. This is done using a file called `Dockerfile`. To begin with, the
 Dockerfile consists of:
 
     FROM ruby:2.2.0
-    RUN apt-get update -qq && apt-get install -y build-essential libpq-dev
+    RUN apt-get update -qq && apt-get install -y build-essential libpq-dev nodejs
     RUN mkdir /myapp
     WORKDIR /myapp
     ADD Gemfile /myapp/Gemfile

docs/reference/down.md

@@ -12,17 +12,27 @@ parent = "smn_compose_cli"
 # down
 
 ```
-Stop containers and remove containers, networks, volumes, and images
-created by `up`. Only containers and networks are removed by default.
-
 Usage: down [options]
 
 Options:
-    --rmi type          Remove images, type may be one of: 'all' to remove
+    --rmi type          Remove images. Type must be one of:
-                        all images, or 'local' to remove only images that
+                        'all': Remove all images used by any service.
-                        don't have an custom name set by the `image` field
+                        'local': Remove only images that don't have a custom tag
-    -v, --volumes       Remove data volumes
+                        set by the `image` field.
-
+    -v, --volumes       Remove named volumes declared in the `volumes` section
+                        of the Compose file and anonymous volumes
+                        attached to containers.
     --remove-orphans    Remove containers for services not defined in the
                         Compose file
 ```
+
+Stops containers and removes containers, networks, volumes, and images
+created by `up`.
+
+By default, the only things removed are:
+
+- Containers for services defined in the Compose file
+- Networks defined in the `networks` section of the Compose file
+- The default network, if one is used
+
+Networks and volumes defined as `external` are never removed.

docs/reference/rm.md

@@ -15,14 +15,15 @@ parent = "smn_compose_cli"
 Usage: rm [options] [SERVICE...]
 
 Options:
--f, --force   Don't ask to confirm removal
+    -f, --force   Don't ask to confirm removal
--v            Remove volumes associated with containers
+    -v            Remove any anonymous volumes attached to containers
--a, --all     Also remove one-off containers
+    -a, --all     Also remove one-off containers created by
+                  docker-compose run
 ```
 
 Removes stopped service containers.
 
-By default, volumes attached to containers will not be removed. You can see all
+By default, anonymous volumes attached to containers will not be removed. You
-volumes with `docker volume ls`.
+can override this with `-v`. To list all volumes, use `docker volume ls`.
 
 Any data which is not in a volume will be lost.

docs/wordpress.md

@@ -16,13 +16,13 @@ You can use Docker Compose to easily run WordPress in an isolated environment bu
 with Docker containers. This quick-start guide demonstrates how to use Compose to set up and run WordPress. Before starting, you'll need to have
 [Compose installed](install.md).
 
-## Define the project
+### Define the project
 
 1. Create an empty project directory.
 
     You can name the directory something easy for you to remember. This directory is the context for your application image. The directory should only contain resources to build that image.
 
-    This project directory will contain a `Dockerfile`, a `docker-compose.yaml` file, along with a downloaded `wordpress` directory and a custom `wp-config.php`, all of which you will create in the following steps.
+    This project directory will contain a `docker-compose.yaml` file which will be complete in itself for a good starter wordpress project.
 
 2. Change directories into your project directory.
 
@@ -30,109 +30,72 @@ with Docker containers. This quick-start guide demonstrates how to use Compose t
 
         $ cd my-wordpress/
 
-3. Create a `Dockerfile`, a file that defines the environment in which your application will run.
+3. Create a `docker-compose.yml` file that will start your `Wordpress` blog and a separate `MySQL` instance with a volume mount for data persistence:
-
-    For more information on how to write Dockerfiles, see the [Docker Engine user guide](https://docs.docker.com/engine/userguide/dockerimages/#building-an-image-from-a-dockerfile) and the [Dockerfile reference](https://docs.docker.com/engine/reference/builder/).
-
-    In this case, your Dockerfile should include these two lines:
-
-        FROM orchardup/php5
-        ADD . /code
-
-    This tells the Docker Engine daemon how to build an image defining a container that contains PHP and WordPress.
-
-4. Create a `docker-compose.yml` file that will start your web service and a separate MySQL instance:
 
         version: '2'
         services:
-          web:
+          db:
-            build: .
+            image: mysql:5.7
-            command: php -S 0.0.0.0:8000 -t /code/wordpress/
+            volumes:
-            ports:
+              - "./.data/db:/var/lib/mysql"
-              - "8000:8000"
+            restart: always
+            environment:
+              MYSQL_ROOT_PASSWORD: wordpress
+              MYSQL_DATABASE: wordpress
+              MYSQL_USER: wordpress
+              MYSQL_PASSWORD: wordpress
+
+          wordpress:
             depends_on:
               - db
-            volumes:
+            image: wordpress:latest
-              - .:/code
+            links:
-          db:
+              - db
-            image: orchardup/mysql
+            ports:
+              - "8000:80"
+            restart: always
             environment:
-              MYSQL_DATABASE: wordpress
+              WORDPRESS_DB_HOST: db:3306
+              WORDPRESS_DB_PASSWORD: wordpress
 
-5. Download WordPress into the current directory:
+    **NOTE**: The folder `./.data/db` will be automatically created in the project directory
-
+    alongside the `docker-compose.yml` which will persist any updates made by wordpress to the
-        $ curl https://wordpress.org/latest.tar.gz | tar -xvzf -
+    database.
-
-    This creates a directory called `wordpress` in your project directory.
-
-6. Create a `wp-config.php` file within the `wordpress` directory.
-
-    A supporting file is needed to get this working. At the top level of the wordpress directory, add a new file called `wp-config.php` as shown. This is the standard WordPress config file with a single change to point the database configuration at the `db` container:
-
-        <?php
-        define('DB_NAME', 'wordpress');
-        define('DB_USER', 'root');
-        define('DB_PASSWORD', '');
-        define('DB_HOST', "db:3306");
-        define('DB_CHARSET', 'utf8');
-        define('DB_COLLATE', '');
-
-        define('AUTH_KEY',         'put your unique phrase here');
-        define('SECURE_AUTH_KEY',  'put your unique phrase here');
-        define('LOGGED_IN_KEY',    'put your unique phrase here');
-        define('NONCE_KEY',        'put your unique phrase here');
-        define('AUTH_SALT',        'put your unique phrase here');
-        define('SECURE_AUTH_SALT', 'put your unique phrase here');
-        define('LOGGED_IN_SALT',   'put your unique phrase here');
-        define('NONCE_SALT',       'put your unique phrase here');
-
-        $table_prefix  = 'wp_';
-        define('WPLANG', '');
-        define('WP_DEBUG', false);
-
-        if ( !defined('ABSPATH') )
-          define('ABSPATH', dirname(__FILE__) . '/');
-
-        require_once(ABSPATH . 'wp-settings.php');
-        ?>
-
-7. Verify the contents and structure of your project directory.
-<!--
-        Dockerfile
-        docker-compose.yaml
-        wordpress/
-          index.php
-          license.txt
-          readme.html
-          wp-activate.php
-          wp-admin/
-          wp-blog-header.php
-          wp-comments-post.php
-          wp-config-sample.php
-          wp-config.php
-          wp-content/
-          wp-cron.php
-          wp-includes/
-          wp-links-opml.php
-          wp-load.php
-          wp-login.php
-          wp-mail.php
-          wp-settings.php
-          wp-signup.php
-          wp-trackback.php
-          xmlrpc.php
-      -->
-
-    ![WordPress files](images/wordpress-files.png)
 
 ### Build the project
 
-With those four new files in place, run `docker-compose up` from your project directory. This will pull and build the needed images, and then start the web and database containers.
+Now, run `docker-compose up -d` from your project directory.
+
+This pulls the needed images, and starts the wordpress and database containers, as shown in the example below.
+
+    $ docker-compose up -d
+    Creating network "my_wordpress_default" with the default driver
+    Pulling db (mysql:5.7)...
+    5.7: Pulling from library/mysql
+    efd26ecc9548: Pull complete
+    a3ed95caeb02: Pull complete
+    ...
+    Digest: sha256:34a0aca88e85f2efa5edff1cea77cf5d3147ad93545dbec99cfe705b03c520de
+    Status: Downloaded newer image for mysql:5.7
+    Pulling wordpress (wordpress:latest)...
+    latest: Pulling from library/wordpress
+    efd26ecc9548: Already exists
+    a3ed95caeb02: Pull complete
+    589a9d9a7c64: Pull complete
+    ...
+    Digest: sha256:ed28506ae44d5def89075fd5c01456610cd6c64006addfe5210b8c675881aff6
+    Status: Downloaded newer image for wordpress:latest
+    Creating my_wordpress_db_1
+    Creating my_wordpress_wordpress_1
+
+### Bring up WordPress in a web browser
 
 If you're using [Docker Machine](https://docs.docker.com/machine/), then `docker-machine ip MACHINE_VM` gives you the machine address and you can open `http://MACHINE_VM_IP:8000` in a browser.
 
 At this point, WordPress should be running on port `8000` of your Docker Host, and you can complete the "famous five-minute installation" as a WordPress administrator.
 
+**NOTE**: The Wordpress site will not be immediately available on port `8000` because the containers are still being initialized and may take a couple of minutes before the first load.
+
 ![Choose language for WordPress install](images/wordpress-lang.png)
 
 ![WordPress Welcome](images/wordpress-welcome.png)