surfacing Learn by example topics to top level of Docker Engine docs

fixing links after moving surfacing tutorials

fixing more links for the newly located tutorials

WIP: merging 3 getting started tutorials into one to cover all platforms, added new files

fixing broken images and links in 3-in-1 getting started, re-wrote story flow, linked to Toolbox, d4mac,d4win

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>
(cherry picked from commit 0254c12e1e0be7a93e3b28e61586ac66168a9b7c)

docs/getstarted/index.md

@@ -0,0 +1,42 @@
+<!--[metadata]>
++++
+aliases = [
+"/mac/started/",
+"/windows/started/",
+"/linux/started/",
+]
+title = "Get Started with Docker"
+description = "Getting started with Docker"
+keywords = ["beginner, getting started, Docker"]
+[menu.main]
+identifier = "getstart_all"
+parent = "engine_use"
+weight="-80"
++++
+<![end-metadata]-->
+
+
+# Get Started with Docker
+
+This tutorial is a for non-technical users who are interested in learning more about Docker. By following these steps, you'll learn fundamental Docker features while working through some simple tasks. You'll learn how to:
+
+* install Docker software for your platform
+* run a software image in a container
+* browse for an image on Docker Hub
+* create your own image and run it in a container
+* create a Docker Hub account and an image repository
+* create an image of your own
+* push your image to Docker Hub for others to use
+
+The getting started was user tested to reduce the chance of users having problems. For the best chance of success, follow the steps as written the first time before exploring on your own. It takes approximately 45 minutes to complete.
+
+
+### Make sure you understand...
+
+This getting started uses Docker Engine CLI commands entered on the command line of a terminal window. You don't need to be a wizard at the command line, but you should be familiar with how to open your favorite shell or terminal, and run basic commands in that environment. It helps (but isn't required) to know how to navigate a directory tree, manipulate files, list running process, and so forth.
+
+
+Go to [the next page to install](step_one.md).
+
+
+&nbsp;

docs/getstarted/last_page.md

@@ -0,0 +1,69 @@
+<!--[metadata]>
++++
+aliases = [
+"/mac/last_page/",
+"/windows/last_page/",
+"/linux/last_page/",
+]
+title = "Learning more"
+description = "Getting started with Docker"
+keywords = ["beginner, getting started, Docker"]
+[menu.main]
+identifier = "getstart_learn_more"
+parent = "getstart_all"
+weight = 7
++++
+<![end-metadata]-->
+
+# Learning more
+
+This getting started provided very basic essentials for using Docker on Mac, Windows, and Linux. If you want to learn more with regard to end-to-end development, start with the full install instructions and feature overviews, then follow up with more advanced tutorials and user guides.
+
+Depending on your interest, the Docker documentation contains a wealth of information.  Here are some places to start:
+
+<style type="text/css">
+</style>
+<table class="tutorial">
+  <tr>
+    <th class="tg-031e">If you are looking for</th>
+    <th class="tg-031e">Where to find it</th>
+  </tr>
+  <tr>
+    <td class="tg-031e">More about Docker for Mac, features, examples, FAQs, relationship to Docker Machine and Docker Toolbox, and how this fits in the Docker ecosystem</td>
+    <td class="tg-031e"><a href="https://docs.docker.com/docker-for-mac/">Getting Started with Docker for Mac</a></td>
+  </tr>
+  <tr>
+    <td class="tg-031e">More about Docker for Windows, More about Docker for Mac, features, examples, FAQs, relationship to Docker Machine and Docker Toolbox, and how this fits in the Docker ecosystem</td>
+    <td class="tg-031e"><a href="https://docs.docker.com/docker-for-windows/">Getting Started with Docker for Windows</a></td>
+  </tr>
+  <tr>
+    <td class="tg-031e">More about Docker Toolbox</td>
+    <td class="tg-031e"><a href="https://docs.docker.com/toolbox/overview/">Docker Toolbox Overview</a></td>
+  </tr>
+  <tr>
+    <td class="tg-031e">More about Docker for Linux distributions</td>
+    <td class="tg-031e"><a href="https://docs.docker.com//engine/installation/linux/">Install Docker Engine on Linux</a></td>
+  </tr>
+  <tr>
+    <td class="tg-031e">More advanced tutorials on running containers, building your own images, networking containers, managing data for containers, and storing images on Docker Hub</td>
+    <td class="tg-031e"> <a href="http://www.docker.com//engine/tutorials/">Learn by example</a></td>
+  </tr>
+  <tr>
+    <td class="tg-031e">Information about the Docker product line</td>
+    <td class="tg-031e"><a href="http://www.docker.com/products">The product explainer is a good place to start.</a></td>
+  </tr>
+
+  <tr>
+    <td class="tg-031e">How to set up an automated build on Docker Hub</td>
+    <td class="tg-031e"><a href="https://docs.docker.com/docker-hub/">Docker Hub documentation</a></td>
+  </tr>
+  <tr>
+    <td class="tg-031e">How to run a multi-container application with Compose</td>
+    <td class="tg-031e"><a href="https://docs.docker.com/compose/gettingstarted/">Docker Compose documentation</a></td>
+  </tr>
+</table>
+
+
+
+
+&nbsp;

docs/getstarted/linux_install_help.md

@@ -0,0 +1,44 @@
+<!--[metadata]>
++++
+aliases = ["/mac/started/"]
+title = "Install Docker and run hello-world"
+description = "Getting started with Docker"
+keywords = ["beginner, getting started, Docker, install"]
+identifier = "getstart_linux_install"
+parent = "getstart_all"
+weight="-80"
++++
+<![end-metadata]-->
+
+# Example: Install Docker on Ubuntu Linux
+
+This installation procedure for users who are unfamiliar with package
+managers, and just want to try out the Getting Started tutorial while running Docker on Linux. If you are comfortable with package managers, prefer not to use
+`curl`, or have problems installing and want to troubleshoot, please use our
+`apt` and `yum` <a href="https://docs.docker.com/engine/installation/"
+target="_blank">repositories instead for your installation</a>.
+
+1. Log into your Ubuntu installation as a user with `sudo` privileges.
+
+2. Verify that you have `curl` installed.
+
+        $ which curl
+
+    If `curl` isn't installed, install it after updating your manager:
+
+        $ sudo apt-get update
+        $ sudo apt-get install curl
+
+3. Get the latest Docker package.
+
+        $ curl -fsSL https://get.docker.com/ | sh
+
+    The system prompts you for your `sudo` password. Then, it downloads and
+    installs Docker and its dependencies.
+
+    >**Note**: If your company is behind a filtering proxy, you may find that the
+    >`apt-key`
+    >command fails for the Docker repo during installation. To work around this,
+    >add the key directly using the following:
+    >
+    >       $ curl -fsSL https://get.docker.com/gpg | sudo apt-key add -

docs/getstarted/step_five.md

@@ -0,0 +1,78 @@
+<!--[metadata]>
++++
+aliases = [
+"/mac/step_five/",
+"/windows/step_five/",
+"/linux/step_five/",
+]
+title = "Create a Docker Hub account & repository"
+description = "Getting started with Docker"
+keywords = ["beginner, getting started, Docker"]
+[menu.main]
+identifier = "getstart_docker_hub"
+parent = "getstart_all"
+weight = 5
++++
+<![end-metadata]-->
+
+# Create a Docker Hub account & repository
+
+You've built something really cool, you should share it. In this next section,
+you'll do just that. You'll need a Docker Hub account. Then, you'll push your
+image up to it so other people with Docker Engine can run it.
+
+
+## Step 1: Sign up for an account
+
+1. Use your browser to navigate to <a href="https://hub.docker.com/?utm_source=getting_started_guide&utm_medium=embedded_MacOSX&utm_campaign=create_docker_hub_account" target="_blank">the Docker Hub signup page</a>.
+
+	Your browser displays the page.
+
+	![Docker Hub signup](tutimg/hub_signup.png)
+
+2. Fill out the form on the signup page.
+
+	Docker Hub is free. Docker does need a name, password, and email address.
+
+3. Press **Signup**.
+
+	The browser displays the welcome to Docker Hub page.
+
+## Step 2: Verify your email and add a repository
+
+Before you can share anything on the hub, you need to verify your email address.
+
+1. Open your email inbox.
+
+2. Look for the email titled `Please confirm email for your Docker Hub account`.
+
+	  If you don't see the email, check your Spam folder or wait a moment for the email to arrive.
+
+2. Open the email and click the **Confirm Your Email** button.
+
+	 The browser opens Docker Hub to your profile page.
+
+4. Choose **Create Repository**.
+
+	The browser opens the **Create Repository** page.
+
+5. Provide a Repository Name and Short Description.
+
+6. Make sure Visibility is set to **Public**.
+
+    When you are done, your form should look similar to the following:
+
+	![Add repo](tutimg/add_repository.png)
+
+6. Press **Create** when you are done.
+
+	Docker Hub creates your new repository.
+
+## Where to go next
+
+On this page, you opened an account on Docker Hub and created a new repository.
+In the next section, you populate the repository [by tagging and pushing the
+image you created earlier](step_six.md).
+
+
+&nbsp;

docs/getstarted/step_four.md

@@ -0,0 +1,227 @@
+<!--[metadata]>
++++
+aliases = [
+"/mac/step_four/",
+"/windows/step_four/",
+"/linux/step_four/",
+]
+title = "Build your own image"
+description = "Getting started with Docker"
+keywords = ["beginner, getting started, Docker"]
+[menu.main]
+identifier = "getstart_build_image"
+parent = "getstart_all"
+weight = 4
++++
+<![end-metadata]-->
+
+# Build your own image
+
+The `whalesay` image could be improved. It would be nice if you didn't have to
+think of something to say. And you type a lot to get `whalesay` to talk.
+
+    docker run docker/whalesay cowsay boo-boo
+
+In this next section, you will improve the `whalesay` image by building a new version that "talks on its own" and requires fewer words to run.
+
+## Step 1: Write a Dockerfile
+
+In this step, you use your favorite text editor to write a short Dockerfile.  A
+Dockerfile describes the software that is "baked" into an image. It isn't just
+ingredients tho, it can tell the software what environment to use or what
+commands to run. Your recipe is going to be very short.
+
+1. Go back to your command terminal window.
+
+2. Make a new directory by typing `mkdir mydockerbuild` and pressing RETURN.
+
+        $ mkdir mydockerbuild
+
+    This directory serves as the "context" for your build. The context just means it contains all the things you need to build your image.
+
+3. Change to your new directory.
+
+        $ cd mydockerbuild
+
+    Right now the directory is empty.
+
+4. Create a Dockerfile in the directory by typing `touch Dockerfile` and pressing RETURN.
+
+        $ touch Dockerfile
+
+    The command appears to do nothing but it actually creates the Dockerfile in the current directory.  Just type `ls Dockerfile` to see it.
+
+        $ ls Dockerfile
+        Dockerfile
+
+5. Open the `Dockerfile` in a visual text editor like <a href="https://atom.io/" target="_blank">Atom</a> or <a href="https://www.sublimetext.com/" target="_blank">Sublime</a>, or a text based editor like `vi`, or `nano` (https://www.nano-editor.org/).
+
+6. Add a line to the file like this:
+
+        FROM docker/whalesay:latest
+
+  The `FROM` keyword tells Docker which image your image is based on. Whalesay is cute and has the `cowsay` program already, so we'll start there.
+
+7. Now, add the `fortunes` program to the image.
+
+        RUN apt-get -y update && apt-get install -y fortunes
+
+  The `fortunes` program has a command that prints out wise sayings for our
+  whale to say. So, the first step is to install it. This line installs the
+  software into the image.
+
+8. Once the image has the software it needs, you instruct the software to run
+    when the image is loaded.
+
+          CMD /usr/games/fortune -a | cowsay
+
+    This line tells the `fortune` program to pass a nifty quote to the `cowsay` program.
+
+9. Check your work, your file should look like this:
+
+        FROM docker/whalesay:latest
+        RUN apt-get -y update && apt-get install -y fortunes
+        CMD /usr/games/fortune -a | cowsay
+
+10. Save and close your Dockerfile.
+
+    At this point, you have all your software ingredients and behaviors described in a Dockerfile. You are ready to build a new image.
+
+## Step 2: Build an image from your Dockerfile
+
+1. At the command line, make sure the Dockerfile is in the current directory by typing `cat Dockerfile`
+
+        $ cat Dockerfile
+        FROM docker/whalesay:latest
+
+        RUN apt-get -y update && apt-get install -y fortunes
+
+        CMD /usr/games/fortune -a | cowsay
+
+2. Now, build your new image by typing the `docker build -t docker-whale .` command in your terminal (don't forget the . period).
+
+        $ docker build -t docker-whale .
+        Sending build context to Docker daemon 158.8 MB
+        ...snip...
+        Removing intermediate container a8e6faa88df3
+        Successfully built 7d9495d03763
+
+	  The command takes several seconds to run and reports its outcome. Before
+    you do anything with the new image, take a minute to learn about the
+    Dockerfile build process.
+
+## Step 3: Learn about the build process
+
+The `docker build -t docker-whale .` command takes the `Dockerfile` in the
+current directory, and builds an image called `docker-whale` on your local
+machine. The command takes about a minute and its output looks really long and
+complex. In this section, you learn what each message means.
+
+First Docker checks to make sure it has everything it needs to build.
+
+    Sending build context to Docker daemon 158.8 MB
+
+Then, Docker loads with the `whalesay` image.	It already has this image
+locally as you might recall from the last page. So, Docker doesn't need to
+download it.
+
+    Step 0 : FROM docker/whalesay:latest
+     ---> fb434121fc77
+
+Docker moves onto the next step which is to update the `apt-get` package
+manager. This takes a lot of lines, no need to list them all again here.
+
+    Step 1 : RUN apt-get -y update && apt-get install -y fortunes
+     ---> Running in 27d224dfa5b2
+    Ign http://archive.ubuntu.com trusty InRelease
+    Ign http://archive.ubuntu.com trusty-updates InRelease
+    Ign http://archive.ubuntu.com trusty-security InRelease
+    Hit http://archive.ubuntu.com trusty Release.gpg
+    ....snip...
+    Get:15 http://archive.ubuntu.com trusty-security/restricted amd64 Packages [14.8 kB]
+    Get:16 http://archive.ubuntu.com trusty-security/universe amd64 Packages [134 kB]
+    Reading package lists...
+    ---> eb06e47a01d2
+
+Then, Docker installs the new `fortunes` software.
+
+    Removing intermediate container e2a84b5f390f
+    Step 2 : RUN apt-get install -y fortunes
+     ---> Running in 23aa52c1897c
+    Reading package lists...
+    Building dependency tree...
+    Reading state information...
+    The following extra packages will be installed:
+      fortune-mod fortunes-min librecode0
+    Suggested packages:
+      x11-utils bsdmainutils
+    The following NEW packages will be installed:
+      fortune-mod fortunes fortunes-min librecode0
+    0 upgraded, 4 newly installed, 0 to remove and 3 not upgraded.
+    Need to get 1961 kB of archives.
+    After this operation, 4817 kB of additional disk space will be used.
+    Get:1 http://archive.ubuntu.com/ubuntu/ trusty/main librecode0 amd64 3.6-21 [771 kB]
+    ...snip......
+    Setting up fortunes (1:1.99.1-7) ...
+    Processing triggers for libc-bin (2.19-0ubuntu6.6) ...
+     ---> c81071adeeb5
+    Removing intermediate container 23aa52c1897c
+
+Finally, Docker finishes the build and reports its outcome.		
+
+    Step 3 : CMD /usr/games/fortune -a | cowsay
+     ---> Running in a8e6faa88df3
+     ---> 7d9495d03763
+    Removing intermediate container a8e6faa88df3
+    Successfully built 7d9495d03763
+
+
+## Step 4: Run your new docker-whale
+
+In this step, you verify the new images is on your computer and then you run your new image.
+
+1. Open a command line terminal.
+
+2. Type `docker images` and press RETURN.
+
+    This command, you might remember, lists the images you have locally.
+
+        $ docker images
+        REPOSITORY           TAG          IMAGE ID          CREATED             VIRTUAL SIZE
+        docker-whale         latest       7d9495d03763      4 minutes ago       273.7 MB
+        docker/whalesay      latest       fb434121fc77      4 hours ago         247 MB
+        hello-world          latest       91c95931e552      5 weeks ago         910 B
+
+3. Run your new image by typing `docker run docker-whale` and pressing RETURN.
+
+        $ docker run docker-whale
+         _________________________________________
+        / "He was a modest, good-humored boy. It  \
+        \ was Oxford that made him insufferable." /
+         -----------------------------------------
+                  \
+                   \
+                    \     
+                                  ##        .            
+                            ## ## ##       ==            
+                         ## ## ## ##      ===            
+                     /""""""""""""""""___/ ===        
+                ~~~ {~~ ~~~~ ~~~ ~~~~ ~~ ~ /  ===- ~~~   
+                     \______ o          __/            
+                      \    \        __/             
+                        \____\______/   
+
+As you can see, you've made the whale a lot smarter. It finds its own
+things to say and the command line is a lot shorter!  You may also notice
+that Docker didn't have to download anything.  That is because the image was
+built locally and is already available.
+
+## Where to go next
+
+On this page, you learned to build an image by writing your own Dockerfile.
+You ran your image in a container. You also just used Linux from your Mac yet
+again. In the next section, you take the first step in sharing your image by
+[creating a Docker Hub account](step_five.md).
+
+
+&nbsp;

docs/getstarted/step_one.md

@@ -0,0 +1,141 @@
+<!--[metadata]>
++++
+aliases = [
+"/mac/step_one/",
+"/windows/step_one/",
+"/linux/step_one/",
+]
+title = "Install Docker and run hello-world"
+description = "Getting started with Docker"
+keywords = ["beginner, getting started, Docker, install"]
+[menu.main]
+identifier = "getstart_all_install"
+parent = "getstart_all"
+weight = 1
++++
+<![end-metadata]-->
+
+# Install Docker
+
+## Step 1: Get Docker
+
+### Docker for Mac
+
+Docker for Mac is our newest offering for the Mac. It runs as a native Mac application and uses <a href="https://github.com/mist64/xhyve/" target="_blank">xhyve</a> to virutalize the Docker Engine environment and Linux kernel-specific features for the Docker daemon.
+
+<a class="button" href="https://download.docker.com/mac/beta/Docker.dmg">Get Docker for Mac</a>
+
+#### Install Prequisites
+
+- Mac must be a 2010 or newer model, with Intel's hardware support for memory management unit (MMU) virtualization; i.e., Extended Page Tables (EPT)
+
+- OS X 10.10.3 Yosemite or newer
+
+- At least 4GB of RAM
+
+- VirtualBox prior to version 4.3.30 must NOT be installed (it is incompatible with Docker for Mac). Docker for Mac will error out on install in this case. Uninstall the older version of VirtualBox and re-try the install.
+
+#### Docker Toolbox for the Mac
+
+If you have an earlier Mac that doesn't meet the Docker for Mac prerequisites, <a href="https://www.docker.com/products/docker-toolbox" target="_blank">get Docker Toolbox</a> for the Mac.
+
+See [Docker Toolbox Overview](toolbox/overview/) for help on installing Docker with Toolbox.
+
+### Docker for Windows
+
+Docker for Windows is our newest offering for PCs. It runs as a native Windows application and uses Hyper-V to virutalize the Docker Engine environment and Linux kernel-specific features for the Docker daemon.
+
+<a class="button" href="https://download.docker.com/win/beta/InstallDocker.msi">Get Docker for Windows</a>
+
+
+#### Install Prequisites
+
+* 64bit Windows 10 Pro, Enterprise and Education (1511 November update, Build 10586 or later). In the future we will support more versions of Windows 10.
+
+* The Hyper-V package must be enabled. The Docker for Windows installer will enable it for you, if needed. (This requires a reboot).
+
+#### Docker Toolbox for Windows
+
+If you have an earlier Windows system that doesn't meet the Docker for Windows prerequisites, <a href="https://www.docker.com/products/docker-toolbox" target="_blank">get Docker Toolbox</a>.
+
+See [Docker Toolbox Overview](toolbox/overview/) for help on installing Docker with Toolbox.
+
+### Docker for Linux
+Docker Engine runs navitvely on Linux distributions.
+
+For full instructions on getting Docker for various Linux distributions, see [Install Docker Engine](/engine/installation/).
+
+## Step 2: Install Docker
+
+* For install instructions for Docker for Mac, see [Getting Started with Docker for Mac](/docker-for-mac/).
+
+* For install instructions for Docker for Windows, see [Getting Started with Docker for Windows](/docker-for-windows/).
+
+* For install instructions for Docker Toolbox, see [Docker Toolbox Overview](toolbox/overview/).
+
+* For a simple example of installing Docker on Ubuntu Linux so that you can work through this tutorial, see [Installing Docker on Ubuntu Linux (Example)](linux_install_help.md).
+
+  For full install instructions for Docker on Linux, see [Install Docker Engine](/engine/installation/) and select the flavor of Linux you want to use.
+
+## Step 3: Verify your installation
+
+1. Open a command-line terminal, and run some Docker commands to verify that Docker is working as expected.
+
+  Some good commands to try are `docker version` to check that you have the latest release installed and `docker ps` to see if you have any running containers. (Probably not, since you just started.)
+
+2. Type the `docker run hello-world` command and press RETURN.
+
+    The command does some work for you, if everything runs well, the command's
+    output looks like this:
+
+        $ docker run hello-world
+        Unable to find image 'hello-world:latest' locally
+        latest: Pulling from library/hello-world
+        535020c3e8ad: Pull complete
+        af340544ed62: Pull complete
+        Digest: sha256:a68868bfe696c00866942e8f5ca39e3e31b79c1e50feaee4ce5e28df2f051d5c
+        Status: Downloaded newer image for hello-world:latest
+
+        Hello from Docker.
+        This message shows that your installation appears to be working correctly.
+
+        To generate this message, Docker took the following steps:
+        1. The Docker Engine CLI client contacted the Docker Engine daemon.
+        2. The Docker Engine daemon pulled the "hello-world" image from the Docker Hub.
+        3. The Docker Engine daemon created a new container from that image which runs the
+           executable that produces the output you are currently reading.
+        4. The Docker Engine daemon streamed that output to the Docker Engine CLI client, which sent it
+           to your terminal.
+
+        To try something more ambitious, you can run an Ubuntu container with:
+        $ docker run -it ubuntu bash
+
+        Share images, automate workflows, and more with a free Docker Hub account:
+        https://hub.docker.com
+
+        For more examples and ideas, visit:
+        https://docs.docker.com/userguide/
+
+3. Run `docker ps -a` to show all containers on the system.
+
+        $ docker ps -a
+
+        CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS                      PORTS               NAMES
+        592376ff3eb8        hello-world         "/hello"            25 seconds ago      Exited (0) 24 seconds ago                       prickly_wozniak
+
+    You should see your `hello-world` container listed in the output for the `docker ps -a` command.
+
+    The command `docker ps` shows only currently running containers. Since `hello-world` already ran and exited, it wouldn't show up with a `docker ps`.
+
+## Looking for troubleshooting help?
+
+Typically, the above steps work out-of-the-box, but some scenarios can cause problems. If your `docker run hello-world` didn't work and resulted in errors, check out [Troubleshooting](/tutorials/faqs/troubleshoot.md) for quick fixes to common problems.
+
+## Where to go next
+
+At this point, you have successfully installed the Docker software. Leave the
+Docker Quickstart Terminal window open. Now, go to the next page to [read a very
+short introduction Docker images and containers](step_two.md).
+
+
+&nbsp;

docs/getstarted/step_six.md

@@ -0,0 +1,205 @@
+<!--[metadata]>
++++
+aliases = [
+"/mac/step_six/",
+"/windows/step_six/",
+"/linux/step_six/",
+]
+title = "Tag, push, & pull your image"
+description = "Getting started with Docker"
+keywords = ["beginner, getting started, Docker"]
+[menu.main]
+identifier = "getstart_tag_push_pull"
+parent = "getstart_all"
+weight = 6
++++
+<![end-metadata]-->
+
+
+# Tag, push, and pull your image
+
+In this section, you tag and push your `docker-whale` image to your newly
+created repository. When you are done, you test the repository by pulling your
+new image.
+
+## Step 1: Tag and push the image
+
+If you don't already have a terminal open, open one now:
+
+1. Go back to your command line terminal.
+
+2. At the prompt, type `docker images` to list the images you currently have:
+
+        $ docker images
+        REPOSITORY           TAG          IMAGE ID            CREATED             VIRTUAL SIZE
+        docker-whale         latest       7d9495d03763        38 minutes ago      273.7 MB
+        <none>               <none>       5dac217f722c        45 minutes ago      273.7 MB
+        docker/whalesay      latest       fb434121fc77        4 hours ago         247 MB
+        hello-world          latest       91c95931e552        5 weeks ago         910 B
+
+5. Find the `IMAGE ID` for your `docker-whale` image.
+
+  	 In this example, the id is `7d9495d03763`.
+
+     Notice that currently, the `REPOSITORY` shows the repo name `docker-whale`
+     but not the namespace. You need to include the `namespace` for Docker Hub to
+     associate it with your account. The `namespace` is the same as your Docker
+     Hub account name. You need to rename the image to
+     `YOUR_DOCKERHUB_NAME/docker-whale`.
+
+6. Use `IMAGE ID` and the `docker tag` command to tag your `docker-whale` image.
+
+    The command you type looks like this:
+
+    ![Docker tag command](tutimg/tagger.png)
+
+    Of course, your account name will be your own. So, you type the command with
+    your image's ID and your account name and press RETURN.
+
+		$ docker tag 7d9495d03763 maryatdocker/docker-whale:latest
+
+7. Type the `docker images` command again to see your newly tagged image.
+
+        $ docker images
+        REPOSITORY                  TAG       IMAGE ID        CREATED          VIRTUAL SIZE
+        maryatdocker/docker-whale   latest    7d9495d03763    5 minutes ago    273.7 MB
+        docker-whale                latest    7d9495d03763    2 hours ago      273.7 MB
+        <none>                      <none>    5dac217f722c    5 hours ago      273.7 MB
+        docker/whalesay             latest    fb434121fc77    5 hours ago      247 MB
+        hello-world                 latest    91c95931e552    5 weeks ago      910 B
+
+8. Use the `docker login` command to log into the Docker Hub from the command line.
+
+    The format for the login command is:
+
+        docker login --username=yourhubusername --email=youremail@company.com
+
+    When prompted, enter your password and press enter. So, for example:
+
+        $ docker login --username=maryatdocker --email=mary@docker.com
+        Password:
+        WARNING: login credentials saved in C:\Users\sven\.docker\config.json
+        Login Succeeded
+
+9. Type the `docker push` command to push your image to your new repository.
+
+		$ docker push maryatdocker/docker-whale
+			The push refers to a repository [maryatdocker/docker-whale] (len: 1)
+			7d9495d03763: Image already exists
+			c81071adeeb5: Image successfully pushed
+			eb06e47a01d2: Image successfully pushed
+			fb434121fc77: Image successfully pushed
+			5d5bd9951e26: Image successfully pushed
+			99da72cfe067: Image successfully pushed
+			1722f41ddcb5: Image successfully pushed
+			5b74edbcaa5b: Image successfully pushed
+			676c4a1897e6: Image successfully pushed
+			07f8e8c5e660: Image successfully pushed
+			37bea4ee0c81: Image successfully pushed
+			a82efea989f9: Image successfully pushed
+			e9e06b06e14c: Image successfully pushed
+			Digest: sha256:ad89e88beb7dc73bf55d456e2c600e0a39dd6c9500d7cd8d1025626c4b985011
+
+10. Return to your profile on Docker Hub to see your new image.
+
+  ![Docker tag command](tutimg/new_image.png)
+
+## Step 2: Pull your new image
+
+In this last section, you'll pull the image you just pushed to hub. Before you
+do that though, you'll need to remove the original image from your local
+machine. If you left the original image on your machine. Docker would not pull
+from the hub &mdash; why would it? The two images are identical.
+
+1. Make sure Docker is running, and open a command line terminal.
+
+2. At the prompt, type `docker images` to list the images you currently have on your local machine.
+
+		$ docker images
+		REPOSITORY                  TAG       IMAGE ID        CREATED          VIRTUAL SIZE
+		maryatdocker/docker-whale   latest    7d9495d03763    5 minutes ago    273.7 MB
+		docker-whale                latest    7d9495d03763    2 hours ago      273.7 MB
+		<none>                      <none>    5dac217f722c    5 hours ago      273.7 MB
+		docker/whalesay             latest    fb434121fc77    5 hours ago      247 MB
+		hello-world                 latest    91c95931e552    5 weeks ago      910 B
+
+    To make a good test, you need to remove the `maryatdocker/docker-whale` and
+   `docker-whale` images from your local system. Removing them forces the next
+   `docker pull` to get the image from your repository.
+
+3. Use the `docker rmi` to remove the `maryatdocker/docker-whale` and `docker-whale`
+images.
+
+	You can use an ID or the name to remove an image.
+
+		$ docker rmi -f 7d9495d03763
+		$ docker rmi -f docker-whale
+
+4. Pull and load a new image from your repository using the `docker run` command.
+
+    The command you type should include your username from Docker Hub.
+
+         docker run yourusername/docker-whale
+
+	Since the image is no longer available on your local system, Docker downloads it.
+
+		$ docker run maryatdocker/docker-whale
+		Unable to find image 'maryatdocker/docker-whale:latest' locally
+		latest: Pulling from maryatdocker/docker-whale
+		eb06e47a01d2: Pull complete
+		c81071adeeb5: Pull complete
+		7d9495d03763: Already exists
+		e9e06b06e14c: Already exists
+		a82efea989f9: Already exists
+		37bea4ee0c81: Already exists
+		07f8e8c5e660: Already exists
+		676c4a1897e6: Already exists
+		5b74edbcaa5b: Already exists
+		1722f41ddcb5: Already exists
+		99da72cfe067: Already exists
+		5d5bd9951e26: Already exists
+		fb434121fc77: Already exists
+		Digest: sha256:ad89e88beb7dc73bf55d456e2c600e0a39dd6c9500d7cd8d1025626c4b985011
+		Status: Downloaded newer image for maryatdocker/docker-whale:latest
+         ________________________________________
+        / Having wandered helplessly into a      \
+        | blinding snowstorm Sam was greatly     |
+        | relieved to see a sturdy Saint Bernard |
+        | dog bounding toward him with the       |
+        | traditional keg of brandy strapped to  |
+        | his collar.                            |
+        |                                        |
+        | "At last," cried Sam, "man's best      |
+        \ friend -- and a great big dog, too!"   /
+         ----------------------------------------
+                        \
+                         \
+                          \
+                                  ##        .
+                            ## ## ##       ==
+                         ## ## ## ##      ===
+                     /""""""""""""""""___/ ===
+                ~~~ {~~ ~~~~ ~~~ ~~~~ ~~ ~ /  ===- ~~~
+                     \______ o          __/
+                      \    \        __/
+                        \____\______/
+
+## Where to go next
+
+You've done a lot, you've done all of the following fundamental Docker tasks.
+
+* installed Docker
+* run a software image in a container
+* located an interesting image on Docker Hub
+* run the image on your own machine
+* modified an image to create your own and run it
+* create a Docker Hub account and repository
+* pushed your image to Docker Hub for others to share
+
+<a href="https://twitter.com/intent/tweet?button_hashtag=dockerdocs&text=Just%20ran%20a%20container%20with%20an%20image%20I%20built.%20Find%20it%20on%20%23dockerhub.%20Build%20your%20own%3A%20http%3A%2F%2Fgoo.gl%2FMUi7cA" class="twitter-hashtag-button" data-size="large" data-related="docker" target="_blank">Tweet your accomplishment!</a>
+<script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?'http':'https';if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+'://platform.twitter.com/widgets.js';fjs.parentNode.insertBefore(js,fjs);}}(document, 'script', 'twitter-wjs');</script>
+
+You've only scratched the surface of what Docker can do. Go to the next page to [learn more](last_page.md).
+
+
+&nbsp;

docs/getstarted/step_three.md

@@ -0,0 +1,143 @@
+<!--[metadata]>
++++
+aliases = [
+"/mac/step_three/",
+"/windows/step_three/",
+"/linux/step_three/",
+]
+title = "Find & run the whalesay image"
+description = "Getting started with Docker"
+keywords = ["beginner, getting started, Docker"]
+[menu.main]
+identifier = "getstart_locate"
+parent = "getstart_all"
+weight = 3
++++
+<![end-metadata]-->
+
+# Find and run the whalesay image
+
+People all over the world create Docker images. You can find these images by
+browsing the Docker Hub. In this next section, you'll search for and find the
+image you'll use in the rest of this getting started.
+
+## Step 1: Locate the whalesay image
+
+1. Open your browser and  <a href="https://hub.docker.com/?utm_source=getting_started_guide&utm_medium=embedded_MacOSX&utm_campaign=find_whalesay" target=_blank> browse to the Docker Hub</a>.
+
+    ![Browse Docker Hub](tutimg/browse_and_search.png)
+
+	The Docker Hub contains images from individuals like you and official images
+	from organizations like RedHat, IBM, Google, and a whole lot more.
+
+2. Click **Browse & Search**.
+
+    The browser opens the search page.
+
+3. Enter the word `whalesay` in the search bar.
+
+    ![Browse Docker Hub](tutimg/image_found.png)
+
+4. Click on the **docker/whalesay** image in the results.
+
+    The browser displays the repository for the **whalesay** image.
+
+    ![Browse Docker Hub](tutimg/whale_repo.png)
+
+	  Each image repository contains information about an image. It should
+    include information such as what kind of software the image contains and
+    how to use it. You may notice that the **whalesay** image is based on a
+    Linux distribution called Ubuntu. In the next step, you run the **whalesay** image on your machine.
+
+## Step 2: Run the whalesay image
+
+Make sure Docker is running. On Docker for Mac and Docker for Windows, this is indicated by the Docker whale showing in the status bar.
+
+1. Open a command-line terminal.
+
+2. Type the `docker run docker/whalesay cowsay boo` command and press RETURN.
+
+    This command runs the **whalesay** image in a container. Your terminal should look like the following:
+
+        $ docker run docker/whalesay cowsay boo
+        Unable to find image 'docker/whalesay:latest' locally
+        latest: Pulling from docker/whalesay
+        e9e06b06e14c: Pull complete
+        a82efea989f9: Pull complete
+        37bea4ee0c81: Pull complete
+        07f8e8c5e660: Pull complete
+        676c4a1897e6: Pull complete
+        5b74edbcaa5b: Pull complete
+        1722f41ddcb5: Pull complete
+        99da72cfe067: Pull complete
+        5d5bd9951e26: Pull complete
+        fb434121fc77: Already exists
+        Digest: sha256:d6ee73f978a366cf97974115abe9c4099ed59c6f75c23d03c64446bb9cd49163
+        Status: Downloaded newer image for docker/whalesay:latest
+         _____
+        < boo >
+         -----
+            \
+             \
+              \     
+                            ##        .            
+                      ## ## ##       ==            
+                   ## ## ## ##      ===            
+               /""""""""""""""""___/ ===        
+          ~~~ {~~ ~~~~ ~~~ ~~~~ ~~ ~ /  ===- ~~~   
+               \______ o          __/            
+                \    \        __/             
+                  \____\______/   
+
+	The first time you run a software image, the `docker` command looks for it
+	on your local system. If the image isn't there, then `docker` gets it from
+	the hub.
+
+5. While still in the command line terminal, type `docker images` command and press RETURN.
+
+    The command lists all the images on your local system. You should see
+    `docker/whalesay` in the list.
+
+        $ docker images
+        REPOSITORY           TAG         IMAGE ID            CREATED            VIRTUAL SIZE
+        docker/whalesay      latest      fb434121fc77        3 hours ago        247 MB
+        hello-world          latest      91c95931e552        5 weeks ago        910 B
+
+    When you run an image in a container, Docker downloads the image to your
+    computer. This local copy of the image saves you time.  Docker only
+    downloads the image again if the image's source changes on the hub.  You
+    can, of course, delete the image yourself. You'll learn more about that
+    later. Let's leave the image there for now because we are going to use it
+    later.
+
+6. Take a moment to play with the **whalesay** container a bit.
+
+    Try running the `whalesay` image again with a word or phrase. Try a long or
+    short phrase.  Can you break the cow?
+
+        $ docker run docker/whalesay cowsay boo-boo
+         _________
+        < boo-boo >
+         ---------
+            \
+             \
+              \     
+                            ##        .            
+                      ## ## ##       ==            
+                   ## ## ## ##      ===            
+               /""""""""""""""""___/ ===        
+          ~~~ {~~ ~~~~ ~~~ ~~~~ ~~ ~ /  ===- ~~~   
+               \______ o          __/            
+                \    \        __/             
+                  \____\______/   
+
+## Where to go next
+
+On this page, you learned to search for images on Docker Hub. You used your
+command line to run an image. Think about it, effectively you ran a piece of
+Linux software on your Mac computer.  You learned that running an image copies
+it on your computer.  Now, you are ready to create your own Docker image.
+Go on to the next part [to build your own image](step_four.md).
+
+
+&nbsp;

docs/getstarted/step_two.md

@@ -0,0 +1,46 @@
+<!--[metadata]>
++++
+aliases = [
+"/mac/step_two/",
+"/windows/step_two/",
+"/linux/step_two/",
+]
+title = "Understand images & containers"
+description = "Getting started with Docker"
+keywords = ["beginner, getting started, Docker"]
+[menu.main]
+identifier = "getstart_understand"
+parent = "getstart_all"
+weight = 2
++++
+<![end-metadata]-->
+
+#  Learn about images & containers
+
+Docker Engine provides the core Docker technology that enables images and
+containers. As the last step in your installation, you ran the
+`docker run hello-world` command. The command you ran had three parts.
+
+![Container Explainer](tutimg/container_explainer.png)
+
+An *image* is a filesystem and parameters to use at runtime. It doesn't have
+state and never changes. A *container* is a running instance of an image.
+When you ran the command, Docker Engine:
+
+* checked to see if you had the `hello-world` software image
+* downloaded the image from the Docker Hub (more about the hub later)
+* loaded the image into the container and "ran" it
+
+Depending on how it was built, an image might run a simple, single command and then exit. This is what `Hello-World` did.
+
+A Docker image, though, is capable of much more. An image can start software as complex as a database, wait for you (or someone else) to add data, store the data for later use, and then wait for the next person.
+
+Who built the `hello-world` software image though? In this case, Docker did but anyone can. Docker Engine lets people (or companies) create and share software through Docker images. Using Docker Engine, you don't have to worry about whether your computer can run the software in a Docker image &mdash; a Docker container *can always run it*.
+
+## Where to go next
+
+See, that was quick wasn't it? Now, you are ready to do some really fun stuff with Docker.
+Go on to the next part [to find and run the whalesay image](step_three.md).
+
+
+&nbsp;