Merge pull request docker#5 from ManoMarks/master

Adding in beginner tutorials

Author: vcoisne

README.md

@@ -6,5 +6,5 @@ Index:
 * Docker for [ASP.NET and Windows containers](windows/readme.md)
 * [Docker for Java Developers](java/readme.adoc)
 * [Docker Tutorials from the Community](community-tutorials.md)
-* [Guide to submitting your own tutorial](contriubtions.md)
+* [Guide to submitting your own tutorial](contribute.md)
 * [Docker documentation](https://docs.docker.com)

beginner/chapters/alpine.md

@@ -0,0 +1,102 @@
+## 1.0 Running your first container
+Now that you have everything setup, it's time to get our hands dirty. In this section, you are going to run a [Alpine Linux](http://www.alpinelinux.org/) container (a lightweight linux distribution) on our system and get a taste of the `docker run` command.
+
+To get started, let's run the following in our terminal:
+```
+$ docker pull alpine
+```
+
+> Note: Depending on how you've installed docker on your system, you might see a `permission denied` error after running the above command. If you're on a Mac, [verify your installation](https://docs.docker.com/mac/step_one/). If you're on Linux, you may need to prefix your `docker` commands with `sudo`. Alternatively you can [create a docker group](http://docs.docker.com/engine/installation/ubuntulinux/#create-a-docker-group) to get rid of this issue.
+
+The `pull` command fetches the alpine **image** from the **Docker registry** and saves it in our system. You can use the `docker images` command to see a list of all images on your system.
+```
+$ docker images
+REPOSITORY              TAG                 IMAGE ID            CREATED             VIRTUAL SIZE
+alpine                 latest              c51f86c28340        4 weeks ago         1.109 MB
+hello-world             latest              690ed74de00f        5 months ago        960 B
+```
+
+### 1.1 Docker Run
+Great! Let's now run a Docker **container** based on this image. To do that you are going to use the `docker run` command.
+
+```
+$ docker run alpine ls -l
+total 48
+drwxr-xr-x    2 root     root          4096 Mar  2 16:20 bin
+drwxr-xr-x    5 root     root           360 Mar 18 09:47 dev
+drwxr-xr-x   13 root     root          4096 Mar 18 09:47 etc
+drwxr-xr-x    2 root     root          4096 Mar  2 16:20 home
+drwxr-xr-x    5 root     root          4096 Mar  2 16:20 lib
+......
+......
+```
+What happened? Behind the scenes, a lot of stuff happened. When you call `run`, the Docker client finds the image (alpine in this case), creates the container and then runs a command in that container. When you run `docker run alpine`, you provided a command (`ls -l`), so Docker started the command specified and you saw the listing.
+
+Let's try something more exciting.
+
+```
+$ docker run alpine echo "hello from alpine"
+hello from alpine
+```
+OK, that's some actual output. In this case, the Docker client dutifully ran the `echo` command in our alpine container and then exited it. If you've noticed, all of that happened pretty quickly. Imagine booting up a virtual machine, running a command and then killing it. Now you know why they say containers are fast!
+
+Try another command.
+```
+$ docker run alpine uptime
+00:16:48 up  1:48,  0 users,  load average: 0.00, 0.01, 0.04
+```
+
+Try another command.
+```
+$ docker run alpine /bin/sh
+```
+
+Wait, nothing happened! Is that a bug? Well, no. These interactive shells will exit after running any scripted commands, unless they are run in an interactive terminal - so for this example to not exit, you need to `docker run -it alpine /bin/sh`.
+
+You are now inside the container shell and you can try out a few commands like `ls -l`, `uptime` and others. Exit out of the container by giving the `exit` command.
+
+
+Ok, now it's time to see the `docker ps` command. The `docker ps` command shows you all containers that are currently running.
+
+```
+$ docker ps
+CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES
+```
+
+Since no containers are running, you see a blank line. Let's try a more useful variant: `docker ps -a`
+
+```
+$ docker ps -a
+CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS                      PORTS               NAMES
+36171a5da744        alpine              "/bin/sh"                5 minutes ago       Exited (0) 2 minutes ago                        fervent_newton
+305297d7a235        alpine             "uptime"                  5 minutes ago       Exited (0) 4 minutes ago                        distracted_goldstine
+a6a9d46d0b2f        alpine             "echo 'hello from alp"    6 minutes ago       Exited (0) 6 minutes ago                        lonely_kilby
+ff0a5c3750b9        alpine             "ls -l"                   8 minutes ago       Exited (0) 8 minutes ago                        elated_ramanujan
+c317d0a9e3d2        hello-world         "/hello"                 34 seconds ago      Exited (0) 12 minutes ago                       stupefied_mcclintock
+```
+
+What you see above is a list of all containers that you ran. Notice that the `STATUS` column shows that these containers exited a few minutes ago. You're probably wondering if there is a way to run more than just one command in a container. Let's try that now:
+
+```
+$ docker run -it alpine /bin/sh
+/ # ls
+bin      dev      etc      home     lib      linuxrc  media    mnt      proc     root     run      sbin     sys      tmp      usr      var
+/ # uptime
+ 05:45:21 up  5:58,  0 users,  load average: 0.00, 0.01, 0.04
+```
+Running the `run` command with the `-it` flags attaches us to an interactive tty in the container. Now you can run as many commands in the container as you want. Take some time to run your favorite commands.
+
+> **Danger Zone**: If you're feeling particularly adventurous you can try `rm -rf /bin` in the container. Make sure you run this command in the container and **not** in your laptop. Doing this will not make any other commands like `ls` and `grep` work. Once everything stops working, you can exit the container and then start it up again with the `docker run -it alpine sh` command. Since Docker creates a new container every time, everything should start working again.
+
+That concludes a whirlwind tour of the `docker run` command which would most likely be the command you'll use most often. It makes sense to spend some time getting comfortable with it. To find out more about `run`, use `docker run --help` to see a list of all flags it supports. As you proceed further, we'll see a few more variants of `docker run`.
+### 1.2 Terminology
+In the last section, you saw a lot of Docker-specific jargon which might be confusing to some. So before you go further, let's clarify some terminology that is used frequently in the Docker ecosystem.
+
+- *Images* - The Filesystem and configuration of our application which are used to create containers. To find out more about a Docker image, run `docker inspect alpine`. In the demo above, you used the `docker pull` command to download the **alpine** image. When you executed the command `docker run hello-world`, it also did a `docker pull` behind the scenes to download the **hello-world** image.
+- *Containers* - Created using Docker images and run the actual application. You created a container using `docker run` which you did using the alpine image that you downloaded. A list of running containers can be seen using the `docker ps` command.
+- *Docker daemon* - The background service running on the host that manages building, running and distributing Docker containers.
+- *Docker client* - The command line tool that allows the user to interact with the Docker daemon.
+- *Docker Hub* - A [registry](https://hub.docker.com/explore/) of Docker images. You can think of the registry as a directory of all available Docker images. You'll be using this later in this tutorial.
+
+## Next Steps
+For the next step in the tutorial, head over to [2.0 Webapps with Docker](./webapps.md)

beginner/chapters/setup.md

@@ -0,0 +1,24 @@
+### Prerequisites
+There are no specific skills needed for this tutorial beyond a basic comfort with the command line and using a text editor. Prior experience in developing web applications will be helpful but is not required. As you proceed further along the tutorial, we'll make use of [Docker Hub](https://hub.docker.com/).
+
+### Setting up your computer
+Getting all the tooling setup on your computer can be a daunting task, but thankfully getting Docker up and running on your favorite OS has become very easy.
+
+The *getting started* guide on Docker has detailed instructions for setting up Docker on [Mac](http://docs.docker.com/mac/step_one/), [Linux](http://docs.docker.com/linux/step_one/) and [Windows](http://docs.docker.com/windows/step_one/).
+
+Once you are done installing Docker, test your Docker installation by running the following:
+```
+$ docker run hello-world
+Unable to find image 'hello-world:latest' locally
+latest: Pulling from library/hello-world
+03f4658f8b78: Pull complete
+a3ed95caeb02: Pull complete
+Digest: sha256:8be990ef2aeb16dbcb9271ddfe2610fa6658d13f6dfb8bc72074cc1ca36966a7
+Status: Downloaded newer image for hello-world:latest
+
+Hello from Docker.
+This message shows that your installation appears to be working correctly.
+...
+```
+## Next Steps
+For the next step in the tutorial, head over to [1.0 Running your first container](alpine.md)

beginner/chapters/votingapp.md

@@ -0,0 +1,174 @@
+## 3.0 Run a multi-container app with Docker Compose
+This portion of the tutorial will guide you through the creation and customization of a voting app. It's important that you follow the steps in order, and make sure to customize the portions that are customizable.
+
+**Important.**
+To complete the submission, you will need to have Docker and Docker Compose installed on your machine as mentioned in the [Setup](./setup.md) section. You'll also need to have a [Docker Id](https://hub.docker.com/register/). Once you do run login from the commandline:
+
+```
+$ docker login
+```
+
+And follow the login directions. Now you can push images to Docker Hub.
+
+> Note: If you encounter an error response from daemon while attempting to login, you may need to restart your machine by running `docker-machine restart <YOUR_DOCKER_MACHINE_NAME>`.
+
+
+### 3.1 Get the voting-app
+You now know how to build your own Docker image, so let's take it to the next level and glue things together. For this app you have to run multiple containers and Docker Compose is the best way to do that.
+
+Start by quickly reading the documentation available [here](https://docs.docker.com/compose/overview/).
+
+Clone the voting-app repository already available at [Github Repo](https://github.com/docker/example-voting-app.git).
+
+```
+git clone https://github.com/docker/example-voting-app.git
+```
+
+### 3.2 Customize the app
+
+#### 3.2.1 Modify app.py
+
+In the folder ```example-voting-app/voting-app``` you need to edit the app.py and change the two options for the programming languages you chose.
+
+Edit the following lines:
+
+```
+option_a = os.getenv('OPTION_A', "Java")
+option_b = os.getenv('OPTION_B', "Python")
+```
+
+substituting two options of your choice. For instance:
+
+```
+option_a = os.getenv('OPTION_A', "Cats")
+option_b = os.getenv('OPTION_B', "Dogs")
+```
+#### 3.2.2 Running your app
+Now, run your application. To do that, we'll use [Docker Compose](https://docs.docker.com/compose). Docker Compose is a tool for defining and running multi-container Docker applications. With Compose, you define a `.yml` file that describes all the containers and volumes that you want, and the networks between them. In the example-voting-app directory, you'll see a `docker-compose.yml file`:
+
+```yml
+version: "2"
+
+services:
+  voting-app:
+    build: ./voting-app/.
+    volumes:
+     - ./voting-app:/app
+    ports:
+      - "5000:80"
+    networks:
+      - front-tier
+      - back-tier
+
+  result-app:
+    build: ./result-app/.
+    volumes:
+      - ./result-app:/app
+    ports:
+      - "5001:80"
+    networks:
+      - front-tier
+      - back-tier
+
+  worker:
+    image: manomarks/worker
+    networks:
+      - back-tier
+
+  redis:
+    image: redis:alpine
+    container_name: redis
+    ports: ["6379"]
+    networks:
+      - back-tier
+
+  db:
+    image: postgres:9.4
+    container_name: db
+    volumes:
+      - "db-data:/var/lib/postgresql/data"
+    networks:
+      - back-tier
+
+volumes:
+  db-data:
+
+networks:
+  front-tier:
+  back-tier:
+```
+
+This Compose file defines
+
+- A voting-app container based on a Python image
+- A result-app container based on a Node.js image
+- A redis container based on a redis image, to temporarily store the data.
+- A Java based worker app based on a Java image
+- A Postgres container based on a postgres image
+
+Note that three of the containers are built from Dockerfiles, while the other two are images on Docker Hub. To learn more about how they're built, you can examine each of the Dockerfiles in the two directories: `voting-app`, `result-app`. We included the code for the Java worker in `worker` but pre-built the image to save on downloads.
+
+The Compose file also defines two networks, front-tier and back-tier. Each container is placed on one or two networks. Once on those networks, they can access other services on that network in code just by using the name of the service. To learn more about networking check out the [Networking with Compose documentation](https://docs.docker.com/compose/networking/).
+
+To launch your app navigate to the example-voting-app directory and run the following command:
+
+```
+$ docker-compose up -d
+```
+
+This tells Compose to start all the containers specified in the `docker-compose.yml` file. The `-d` tells it to run them in daemon mode, in the background.
+
+Last you'll need to figure out the ip address of your Docker host. If you're running Linux, it's just localhost, or 127.0.0.1. If you're using Docker Machine on Mac or Windows, you'll need to run:
+
+```
+$ docker-machine ip default
+```
+
+It'll return an IP address. If you only have one Docker Machine running, most likely, that's 192.168.99.100. We'll call that `<YOUR_IP_ADDRESS>`. Navigate to `http://<YOUR_IP_ADDRESS>:5000` in your browser, and you'll see the voting app, something like this:
+
+<img src="../images/vote.png" title="vote">
+
+Click on one to vote. You can check the results at `http://<YOUR_IP_ADDRESS:5001>`.
+
+**NOTE**: If you are running this tutorial in a cloud environment like AWS, Azure, Digital Ocean, or GCE you will not have direct access to localhost or 127.0.0.1 via a browser.  A work around for this is to leverage ssh port forwarding.  Below is an example for Mac OS.  Similarly this can be done for Windows and Putty users.
+
+```
+$ ssh -L 5000:localhost:5000 <ssh-user>@<CLOUD_INSTANCE_IP_ADDRESS>
+```
+
+#### 3.2.3 Build and tag images
+
+You are all set now. Navigate to each of the directories where you have a Dockerfile to build and tag your images that you want to submit.
+
+In order to build the images, make sure to replace `<YOUR_DOCKER_ID>` with your *Docker Hub username* in the following commands:
+
+```
+$ docker build --no-cache -t <YOUR_DOCKER_ID>/votingapp_voting-app .
+...
+$ docker build --no-cache -t <YOUR_DOCKER_ID>/votingapp_result-app .
+...
+$ docker build --no-cache -t <YOUR_DOCKER_ID>/votingapp_worker .
+```
+
+#### 3.2.4 Push images to Docker Hub
+
+Push the images to Docker hub. Remember, you must have run `docker login` before you can push.
+
+```
+$ docker push <YOUR_DOCKER_ID>/votingapp_voting-app
+...
+$ docker push <YOUR_DOCKER_ID>/votingapp_result-app
+...
+$ docker push <YOUR_DOCKER_ID>/votingapp_worker
+```
+
+Now you can access these images anywhere by running
+
+```
+$ docker pull <YOUR_DOCKER_ID>/votingapp_voting-app
+$ docker pull <YOUR_DOCKER_ID>/votingapp_result-app
+$ docker pull <YOUR_DOCKER_ID>/votingapp_worker
+```
+
+### 3.3 Next steps
+Now that you've built some images and pushed them to hub, and learned about Docker Compose, you can explore more of Docker by checking out [the documentation](https://docs.docker.com). And if you need any help, check out the [Docker Forums](forums.docker.com) or [StackOverflow](https://stackoverflow.com/tags/docker/).