Merge pull request #1031 from fredlf/edit-qs-guides

Edits and revisions to Compose Quickstart guides

docs/django.md

@@ -1,14 +1,23 @@
----
-layout: default
-title: Getting started with Compose and Django
----
+page_title: Quickstart Guide: Compose and Django
+page_description: Getting started with Docker Compose and Django
+page_keywords: documentation, docs,  docker, compose, orchestration, containers,
+django
 
-Getting started with Compose and Django
-===================================
 
-Let's use Compose to set up and run a Django/PostgreSQL app. Before starting, you'll need to have [Compose installed](install.md).
+## Getting started with Compose and Django
 
-Let's set up the three files that'll get us started. First, our app is going to be running inside a Docker container which contains all of its dependencies. We can define what goes inside that Docker container using a file called `Dockerfile`. It'll contain this to start with:
+
+This Quick-start Guide will demonstrate how to use 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
+
+Start by setting up the three files you'll need to build the app. First, since
+your app is going to run inside a Docker container containing all of its
+dependencies, you'll need to define exactly what needs to be included in the
+container. This is done using a file called `Dockerfile`. To begin with, the
+Dockerfile consists of:
 
     FROM python:2.7
     ENV PYTHONUNBUFFERED 1
@@ -18,14 +27,21 @@ Let's set up the three files that'll get us started. First, our app is going to
     RUN pip install -r requirements.txt
     ADD . /code/
 
-That'll install our application inside an image with Python installed alongside all of our Python dependencies. 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 Dockerfile will define an image that is used to build a container that
+includes your application and has Python installed alongside all of your Python
+dependencies. 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/).
 
-Second, we define our Python dependencies in a file called `requirements.txt`:
+Second, you'll define your Python dependencies in a file called
+`requirements.txt`:
 
     Django
     psycopg2
 
-Simple enough. Finally, this is all tied together with a file called `docker-compose.yml`. It describes the services that our app comprises of (a web server and database), what Docker images they use, how they link together, what volumes will be mounted inside the containers and what ports they expose.
+Finally, this is all tied together with a file called `docker-compose.yml`. It
+describes the services that comprise your app (here, a web server and database),
+which Docker images they use, how they link together, what volumes will be
+mounted inside the containers, and what ports they expose.
 
     db:
       image: postgres
@@ -39,20 +55,28 @@ Simple enough. Finally, this is all tied together with a file called `docker-com
       links:
         - db
 
-See the [`docker-compose.yml` reference](yml.html) for more information on how it works.
+See the [`docker-compose.yml` reference](yml.html) for more information on how
+this file works.
 
-We can now start a Django project using `docker-compose run`:
+### Build the project
+
+You can now start a Django project with `docker-compose run`:
 
     $ docker-compose run web django-admin.py startproject composeexample .
 
-First, Compose will build an image for the `web` service using the `Dockerfile`. It will then run `django-admin.py startproject composeexample .` inside a container using that image.
+First, Compose will build an image for the `web` service using the `Dockerfile`.
+It will then run `django-admin.py startproject composeexample .` inside a
+container built using that image.
 
 This will generate a Django app inside the current directory:
 
     $ ls
     Dockerfile       docker-compose.yml          composeexample       manage.py        requirements.txt
 
-First thing we need to do is set up the database connection. Replace the `DATABASES = ...` definition in `composeexample/settings.py` to read:
+### Connect the database
+
+Now you need to set up the database connection. Replace the `DATABASES = ...`
+definition in `composeexample/settings.py` to read:
 
     DATABASES = {
         'default': {
@@ -64,7 +88,9 @@ First thing we need to do is set up the database connection. Replace the `DATABA
         }
     }
 
-These settings are determined by the [postgres](https://registry.hub.docker.com/_/postgres/) Docker image we are using.
+These settings are determined by the
+[postgres](https://registry.hub.docker.com/_/postgres/) Docker image specified
+in the Dockerfile.
 
 Then, run `docker-compose up`:
 
@@ -83,13 +109,15 @@ Then, run `docker-compose up`:
     myapp_web_1 | Starting development server at http://0.0.0.0:8000/
     myapp_web_1 | Quit the server with CONTROL-C.
 
-And your Django app should be running at port 8000 on your docker daemon (if you're using boot2docker, `boot2docker ip` will tell you its address).
+Your Django app should nw be running at port 8000 on your Docker daemon (if
+you're using Boot2docker, `boot2docker ip` will tell you its address).
 
-You can also run management commands with Docker. To set up your database, for example, run `docker-compose up` and in another terminal run:
+You can also run management commands with Docker. To set up your database, for
+example, run `docker-compose up` and in another terminal run:
 
     $ docker-compose run web python manage.py syncdb
 
-## Compose documentation
+## More Compose documentation
 
 - [Installing Compose](install.md)
 - [User guide](index.md)

docs/rails.md

@@ -1,14 +1,20 @@
----
-layout: default
-title: Getting started with Compose and Rails
----
+page_title: Quickstart Guide: Compose and Rails
+page_description: Getting started with Docker Compose and Rails
+page_keywords: documentation, docs,  docker, compose, orchestration, containers,
+rails
 
-Getting started with Compose and Rails
-==================================
 
-We're going to use Compose to set up and run a Rails/PostgreSQL app. Before starting, you'll need to have [Compose installed](install.md).
+## Getting started with Compose and Rails
 
-Let's set up the three files that'll get us started. First, our app is going to be running inside a Docker container which contains all of its dependencies. We can define what goes inside that Docker container using a file called `Dockerfile`. It'll contain this to start with:
+This Quickstart guide will show you how to use Compose to set up and run a Rails/PostgreSQL app. Before starting, you'll need to have [Compose installed](install.md).
+
+### Define the project
+
+Start by setting up the three files you'll need to build the app. First, since
+your app is going to run inside a Docker container containing all of its
+dependencies, you'll need to define exactly what needs to be included in the
+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
@@ -18,14 +24,14 @@ Let's set up the three files that'll get us started. First, our app is going to
     RUN bundle install
     ADD . /myapp
 
-That'll put our application code inside an image with Ruby, Bundler and all our dependencies. 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/).
+That'll put your application code inside an image that will build a container with Ruby, Bundler and all your dependencies inside it. 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/).
 
-Next, we have a bootstrap `Gemfile` which just loads Rails. It'll be overwritten in a moment by `rails new`.
+Next, create a bootstrap `Gemfile` which just loads Rails. It'll be overwritten in a moment by `rails new`.
 
     source 'https://rubygems.org'
     gem 'rails', '4.2.0'
 
-Finally, `docker-compose.yml` is where the magic happens. It describes what services our app comprises (a database and a web app), how to get each one's Docker image (the database just runs on a pre-made PostgreSQL image, and the web app is built from the current directory), and the configuration we need to link them together and expose the web app's port.
+Finally, `docker-compose.yml` is where the magic happens. This file describes the services that comprise your app (a database and a web app), how to get each one's Docker image (the database just runs on a pre-made PostgreSQL image, and the web app is built from the current directory), and the configuration needed to link them together and expose the web app's port.
 
     db:
       image: postgres
@@ -41,11 +47,16 @@ Finally, `docker-compose.yml` is where the magic happens. It describes what serv
       links:
         - db
 
-With those files in place, we can now generate the Rails skeleton app using `docker-compose run`:
+### Build the project
+
+With those three files in place, you can now generate the Rails skeleton app
+using `docker-compose run`:
 
     $ docker-compose run web rails new . --force --database=postgresql --skip-bundle
 
-First, Compose will build the image for the `web` service using the `Dockerfile`. Then it'll run `rails new` inside a new container, using that image. Once it's done, you should have a fresh app generated:
+First, Compose will build the image for the `web` service using the
+`Dockerfile`. Then it'll run `rails new` inside a new container, using that
+image. Once it's done, you should have generated a fresh app:
 
     $ ls
     Dockerfile   app          docker-compose.yml      tmp
@@ -54,17 +65,26 @@ First, Compose will build the image for the `web` service using the `Dockerfile`
     README.rdoc  config.ru    public
     Rakefile     db           test
 
-Uncomment the line in your new `Gemfile` which loads `therubyracer`, so we've got a Javascript runtime:
+Uncomment the line in your new `Gemfile` which loads `therubyracer`, so you've
+got a Javascript runtime:
 
     gem 'therubyracer', platforms: :ruby
 
-Now that we've got a new `Gemfile`, we need to build the image again. (This, and changes to the Dockerfile itself, should be the only times you'll need to rebuild).
+Now that you've got a new `Gemfile`, you need to build the image again. (This,
+and changes to the Dockerfile itself, should be the only times you'll need to
+rebuild.)
 
     $ docker-compose build
 
-The app is now bootable, but we're not quite there yet. By default, Rails expects a database to be running on `localhost` - we need to point it at the `db` container instead. We also need to change the database and username to align with the defaults set by the `postgres` image.
+### Connect the database
+
+The app is now bootable, but you're not quite there yet. By default, Rails
+expects a database to be running on `localhost` - so you need to point it at the
+`db` container instead. You also need to change the database and username to
+align with the defaults set by the `postgres` image.
 
-Open up your newly-generated `database.yml`. Replace its contents with the following:
+Open up your newly-generated `database.yml`file. Replace its contents with the
+following:
 
     development: &default
       adapter: postgresql
@@ -79,23 +99,25 @@ Open up your newly-generated `database.yml`. Replace its contents with the follo
       <<: *default
       database: myapp_test
 
-We can now boot the app.
+You can now boot the app with:
 
     $ docker-compose up
 
-If all's well, you should see some PostgreSQL output, and then—after a few seconds—the familiar refrain:
+If all's well, you should see some PostgreSQL output, and then—after a few
+seconds—the familiar refrain:
 
     myapp_web_1 | [2014-01-17 17:16:29] INFO  WEBrick 1.3.1
     myapp_web_1 | [2014-01-17 17:16:29] INFO  ruby 2.2.0 (2014-12-25) [x86_64-linux-gnu]
     myapp_web_1 | [2014-01-17 17:16:29] INFO  WEBrick::HTTPServer#start: pid=1 port=3000
 
-Finally, we just need to create the database. In another terminal, run:
+Finally, you need to create the database. In another terminal, run:
 
     $ docker-compose run web rake db:create
 
-And we're rolling—your app should now be running on port 3000 on your docker daemon (if you're using boot2docker, `boot2docker ip` will tell you its address).
+That's it. Your app should now be running on port 3000 on your Docker daemon (if
+you're using Boot2docker, `boot2docker ip` will tell you its address).
 
-## Compose documentation
+## More Compose documentation
 
 - [Installing Compose](install.md)
 - [User guide](index.md)

docs/wordpress.md

@@ -1,25 +1,40 @@
----
-layout: default
-title: Getting started with Compose and Wordpress
----
+page_title: Quickstart Guide: Compose and Wordpress
+page_description: Getting started with Docker Compose and Rails
+page_keywords: documentation, docs,  docker, compose, orchestration, containers,
+wordpress
 
-Getting started with Compose and Wordpress
-======================================
+## Getting started with Compose and Wordpress
 
-Compose makes it nice and easy to run Wordpress in an isolated environment. [Install Compose](install.md), then download Wordpress into the current directory:
+You can use Compose to easily run Wordpress in an isolated environment built
+with Docker containers. 
+
+### Define the project
+
+First, [Install Compose](install.md) and then download Wordpress into the
+current directory:
 
     $ curl https://wordpress.org/latest.tar.gz | tar -xvzf -
 
-This will create a directory called `wordpress`, which you can rename to the name of your project if you wish. Inside that directory, we create `Dockerfile`, a file that defines what environment your app is going to run in:
+This will create a directory called `wordpress`. If you wish, you can rename it
+to the name of your project.
+
+Next, inside that directory, create a `Dockerfile`, a file that defines what
+environment your app is going to run in. 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/). In this case,
+your Dockerfile should be:
 
 ```
 FROM orchardup/php5
 ADD . /code
 ```
 
-This instructs Docker on how to build an image that contains PHP and Wordpress. 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 how to build an image defining a container that contains PHP
+and Wordpress. 
 
-Next up, `docker-compose.yml` starts our web service and a separate MySQL instance:
+Next you'll create a `docker-compose.yml` file that will start your web service
+and a separate MySQL instance:
 
 ```
 web:
@@ -37,7 +52,9 @@ db:
     MYSQL_DATABASE: wordpress
 ```
 
-Two supporting files are needed to get this working - first up, `wp-config.php` is the standard Wordpress config file with a single change to point the database configuration at the `db` container:
+Two supporting files are needed to get this working - first, `wp-config.php` is
+the standard Wordpress config file with a single change to point the database
+configuration at the `db` container:
 
 ```
 <?php
@@ -67,7 +84,7 @@ if ( !defined('ABSPATH') )
 require_once(ABSPATH . 'wp-settings.php');
 ```
 
-Finally, `router.php` tells PHP's built-in web server how to run Wordpress:
+Second, `router.php` tells PHP's built-in web server how to run Wordpress:
 
 ```
 <?php
@@ -87,10 +104,15 @@ if(file_exists($root.$path))
     }
 }else include_once 'index.php';
 ```
+### Build the project
 
-With those four files in place, run `docker-compose up` inside your Wordpress directory and it'll pull and build the images we need, and then start the web and database containers. You'll then be able to visit Wordpress at port 8000 on your docker daemon (if you're using boot2docker, `boot2docker ip` will tell you its address).
+With those four files in place, run `docker-compose up` inside your Wordpress
+directory and it'll pull and build the needed images, and then start the web and
+database containers. You'll then be able to visit Wordpress at port 8000 on your
+Docker daemon (if you're using Boot2docker, `boot2docker ip` will tell you its
+address).
 
-## Compose documentation
+## More Compose documentation
 
 - [Installing Compose](install.md)
 - [User guide](index.md)