SOURCE: https://docs.docker.com/get-started/

Get Started, Part 1: Orientation and Setup

Estimated reading time: 3 minutes

• 1: Orientation
• 2: Containers
• 3: Services
• 4: Swarms
• 5: Stacks
• 6: Deploy your app

Welcome! We are excited you want to learn how to use Docker.

In this six-part tutorial, you will:

1. Get set up and oriented, on this page.
2. Build and run your first app
3. Turn your app into a scaling service
4. Span your service across multiple machines
5. Add a visitor counter that persists data
6. Deploy your swarm to production

The application itself is very simple so that you are not too distracted by what the code is doing. After all, the value of Docker is in how it can build, ship, and run applications; it’s totally agnostic as to what your application actually does.

Prerequisites

While we’ll define concepts along the way, it is good for you to understand what Docker is and why you would use Docker before we begin.

We also need to assume you are familiar with a few concepts before we continue:

• IP Addresses and Ports
• Virtual Machines
• Editing configuration files
• Basic familiarity with the ideas of code dependencies and building
• Machine resource usage terms, like CPU percentages, RAM use in bytes, etc.

A brief explanation of containers

An image is a lightweight, stand-alone, executable package that includes everything needed to run a piece of software, including the code, a runtime, libraries, environment variables, and config files.

A container is a runtime instance of an image – what the image becomes in memory when actually executed. It runs completely isolated from the host environment by default, only accessing host files and ports if configured to do so.

Containers run apps natively on the host machine’s kernel. They have better performance characteristics than virtual machines that only get virtual access to host resources through a hypervisor. Containers can get native access, each one running in a discrete process, taking no more memory than any other executable.

Containers vs. virtual machines

Consider this diagram comparing virtual machines to containers:

Virtual Machine diagram

Virtual machines run guest operating systems – note the OS layer in each box. This is resource intensive, and the resulting disk image and application state is an entanglement of OS settings, system-installed dependencies, OS security patches, and other easy-to-lose, hard-to-replicate ephemera.

Container diagram

Containers can share a single kernel, and the only information that needs to be in a container image is the executable and its package dependencies, which never need to be installed on the host system. These processes run like native processes, and you can manage them individually by running commands like docker
ps – just like you would run ps on Linux to see active processes. Finally, because they contain all their dependencies, there is no configuration entanglement; a containerized app “runs anywhere.”

Setup

Before we get started, make sure your system has the latest version of Docker installed.

Install Docker

You should be able to run docker run hello-world and see a response like this:

$ docker run hello-world

Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
...(snipped)...

Now would also be a good time to make sure you are using version 1.13 or higher

$ docker --version
Docker version 17.05.0-ce-rc1, build 2878a85

If you see messages like the ones above, you’re ready to begin the journey.

Conclusion

The unit of scale being an individual, portable executable has vast implications. It means that CI/CD can push updates to one part of a distributed application, system dependencies aren’t a thing you worry about, resource density is increased, and orchestrating scaling behavior is a matter of spinning up new executables, not new VM hosts. We’ll be learning about all of those things, but first let’s learn to walk.

On to Part 2 »

Get Started, Part 2: Containers

Estimated reading time: 10 minutes

• 1: Orientation
• 2: Containers
• 3: Services
• 4: Swarms
• 5: Stacks
• 6: Deploy your app

Prerequisites

• Install Docker version 1.13 or higher.
• Read the orientation in Part 1.
• Give your environment a quick test run to make sure you’re all set up:

  docker run hello-world
  

Introduction

It’s time to begin building an app the Docker way. We’ll start at the bottom of the hierarchy of such an app, which is a container, which we cover on this page. Above this level is a service, which defines how containers behave in production, covered in Part 3. Finally, at the top level is the stack, defining the interactions of all the services, covered in Part 5.

• Stack
• Services
• Container (you are here)

Your new development environment

In the past, if you were to start writing a Python app, your first order of business was to install a Python runtime onto your machine. But, that creates a situation where the environment on your machine has to be just so in order for your app to run as expected; ditto for the server that runs your app.

With Docker, you can just grab a portable Python runtime as an image, no installation necessary. Then, your build can include the base Python image right alongside your app code, ensuring that your app, its dependencies, and the runtime, all travel together.

These portable images are defined by something called a Dockerfile.

Define a container with a Dockerfile

Dockerfile will define what goes on in the environment inside your container. Access to resources like networking interfaces and disk drives is virtualized inside this environment, which is isolated from the rest of your system, so you have to map ports to the outside world, and be specific about what files you want to “copy in” to that environment. However, after doing that, you can expect that the build of your app defined in this Dockerfile will behave exactly the same wherever it runs.

Dockerfile

Create an empty directory and put this file in it, with the name Dockerfile. Take note of the comments that explain each statement.

# Use an official Python runtime as a base image
FROM python:2.7-slim

# Set the working directory to /app
WORKDIR /app

# Copy the current directory contents into the container at /app
ADD . /app

# Install any needed packages specified in requirements.txt
RUN pip install -r requirements.txt

# Make port 80 available to the world outside this container
EXPOSE 80

# Define environment variable
ENV NAME World

# Run app.py when the container launches
CMD ["python", "app.py"]

This Dockerfile refers to a couple of things we haven’t created yet, namely app.py and requirements.txt. Let’s get those in place next.

The app itself

Grab these two files and place them in the same folder as Dockerfile. This completes our app, which as you can see is quite simple. When the above Dockerfile is built into an image, app.py and requirements.txt will be present because of that Dockerfile’s ADD command, and the output from app.py will be accessible over HTTP thanks to the EXPOSE command.

requirements.txt

Flask
Redis

app.py

from flask import Flask
from redis import Redis, RedisError
import os
import socket

# Connect to Redis
redis = Redis(host="redis", db=0)

app = Flask(__name__)

@app.route("/")
def hello():
    try:
        visits = redis.incr('counter')
    except RedisError:
        visits = "<i>cannot connect to Redis, counter disabled</i>"

    html = "<h3>Hello {name}!</h3>" \
           "<b>Hostname:</b> {hostname}<br/>" \
           "<b>Visits:</b> {visits}"
    return html.format(name=os.getenv('NAME', "world"), hostname=socket.gethostname(), visits=visits)

if __name__ == "__main__":
	app.run(host='0.0.0.0', port=80)

Now we see that pip install requirements.txt installs the Flask and Redis libraries for Python, and the app prints the environment variable NAME, as well as the output of a call to socket.gethostname(). Finally, because Redis isn’t running (as we’ve only installed the Python library, and not Redis itself), we should expect that the attempt to use it here will fail and produce the error message.

Note: Accessing the name of the host when inside a container retrieves the container ID, which is like the process ID for a running executable.

Build the App

That’s it! You don’t need Python or anything in requirements.txt on your system, nor will building or running this image install them on your system. It doesn’t seem like you’ve really set up an environment with Python and Flask, but you have.

Here’s what ls should show:

$ ls
Dockerfile		app.py			requirements.txt

Now run the build command. This creates a Docker image, which we’re going to tag using -t so it has a friendly name.

docker build -t friendlyhello .

Where is your built image? It’s in your machine’s local Docker image registry:

$ docker images

REPOSITORY            TAG                 IMAGE ID
friendlyhello         latest              326387cea398

Run the app

Run the app, mapping your machine’s port 4000 to the container’s EXPOSEd port 80 using -p:

docker run -p 4000:80 friendlyhello

You should see a notice that Python is serving your app at http://0.0.0.0:80. But that message coming from inside the container, which doesn’t know you mapped port 80 of that container to 4000, making the correct URL http://localhost:4000. Go there, and you’ll see the “Hello World” text, the container ID, and the Redis error message.

Note: This port remapping of 4000:80 is to demonstrate the difference between what you EXPOSE within the Dockerfile, and what you publish using docker run -p. In later steps, we’ll just map port 80 on the host to port 80 in the container and use http://localhost.

Hit CTRL+C in your terminal to quit.

Now let’s run the app in the background, in detached mode:

docker run -d -p 4000:80 friendlyhello

You get the long container ID for your app and then are kicked back to your terminal. Your container is running in the background. You can also see the abbreviated container ID with docker ps (and both work interchangeably when running commands):

$ docker ps
CONTAINER ID        IMAGE               COMMAND             CREATED
1fa4ab2cf395        friendlyhello       "python app.py"     28 seconds ago

You’ll see that CONTAINER ID matches what’s on http://localhost:4000.

Now use docker stop to end the process, using the CONTAINER ID, like so:

docker stop 1fa4ab2cf395

Share your image

To demonstrate the portability of what we just created, let’s upload our build and run it somewhere else. After all, you’ll need to learn how to push to registries to make deployment of containers actually happen.

A registry is a collection of repositories, and a repository is a collection of images – sort of like a GitHub repository, except the code is already built. An account on a registry can create many repositories. The docker CLI is preconfigured to use Docker’s public registry by default.

Note: We’ll be using Docker’s public registry here just because it’s free and pre-configured, but there are many public ones to choose from, and you can even set up your own private registry using Docker Trusted Registry.

If you don’t have a Docker account, sign up for one at cloud.docker.com. Make note of your username.

Log in your local machine.

docker login

Now, publish your image. The notation for associating a local image with a repository on a registry, is username/repository:tag. The :tag is optional, but recommended; it’s the mechanism that registries use to give Docker images a version. So, putting all that together, enter your username, and repo and tag names, so your existing image will upload to your desired destination:

docker tag friendlyhello username/repository:tag

Upload your tagged image:

docker push username/repository:tag

Once complete, the results of this upload are publicly available. From now on, you can use docker run and run your app on any machine with this command:

docker run -p 4000:80 username/repository:tag

Note: If you don’t specify the :tag portion of these commands, the tag of :latest will be assumed, both when you build and when you run images.

No matter where docker run executes, it pulls your image, along with Python and all the dependencies from requirements.txt, and runs your code. It all travels together in a neat little package, and the host machine doesn’t have to install anything but Docker to run it.

Conclusion of part two

That’s all for this page. In the next section, we will learn how to scale our application by running this container in a service.

Continue to Part 3 »

Recap and cheat sheet (optional)

Here’s a terminal recording of what was covered on this page:

Here is a list of the basic commands from this page, and some related ones if you’d like to explore a bit before moving on.

docker build -t friendlyname .  # Create image using this directory's Dockerfile
docker run -p 4000:80 friendlyname  # Run "friendlyname" mapping port 4000 to 80
docker run -d -p 4000:80 friendlyname         # Same thing, but in detached mode
docker ps                                 # See a list of all running containers
docker stop <hash>                     # Gracefully stop the specified container
docker ps -a           # See a list of all containers, even the ones not running
docker kill <hash>                   # Force shutdown of the specified container
docker rm <hash>              # Remove the specified container from this machine
docker rm $(docker ps -a -q)           # Remove all containers from this machine
docker images -a                               # Show all images on this machine
docker rmi <imagename>            # Remove the specified image from this machine
docker rmi $(docker images -q)             # Remove all images from this machine
docker login             # Log in this CLI session using your Docker credentials
docker tag <image> username/repository:tag  # Tag <image> for upload to registry
docker push username/repository:tag            # Upload tagged image to registry
docker run username/repository:tag                   # Run image from a registry

 Estimated reading time:  5 minutes 

version: "3"
services:
  web:
    image: username/repository:tag
    deploy:
      replicas: 5
      resources:
        limits:
          cpus: "0.1"
          memory: 50M
      restart_policy:
        condition: on-failure
    ports:
      - "80:80"
    networks:
      - webnet
networks:
  webnet:

docker swarm init

docker stack deploy -c docker-compose.yml getstartedlab

docker stack ps getstartedlab

docker stack deploy -c docker-compose.yml getstartedlab

docker stack rm getstartedlab

docker stack ls              # List all running applications on this Docker host
docker stack deploy -c <composefile> <appname>  # Run the specified Compose file
docker stack services <appname>       # List the services associated with an app
docker stack ps <appname>   # List the running containers associated with an app
docker stack rm <appname>                             # Tear down an application

 Estimated reading time:  12 minutes 

$ docker-machine create --driver virtualbox myvm1
$ docker-machine create --driver virtualbox myvm2

$ docker-machine ssh myvm1 "docker swarm init"
Swarm initialized: current node <node ID> is now a manager.

To add a worker to this swarm, run the following command:

  docker swarm join \
  --token <token> \
  <ip>:<port>

$ docker-machine ssh myvm2 "docker swarm join \
--token <token> \
<ip>:<port>"

This node joined a swarm as a worker.

docker-machine scp docker-compose.yml myvm1:~

docker-machine ssh myvm1 "docker stack deploy -c docker-compose.yml getstartedlab"

$ docker-machine ssh myvm1 "docker stack ps getstartedlab"

ID            NAME        IMAGE              NODE   DESIRED STATE
jq2g3qp8nzwx  test_web.1  username/repo:tag  myvm1  Running
88wgshobzoxl  test_web.2  username/repo:tag  myvm2  Running
vbb1qbkb0o2z  test_web.3  username/repo:tag  myvm2  Running
ghii74p9budx  test_web.4  username/repo:tag  myvm1  Running
0prmarhavs87  test_web.5  username/repo:tag  myvm2  Running

docker-machine create --driver virtualbox myvm1 # Create a VM (Mac, Win7, Linux)
docker-machine create -d hyperv --hyperv-virtual-switch "myswitch" myvm1 # Win10
docker-machine env myvm1                # View basic information about your node
docker-machine ssh myvm1 "docker node ls"         # List the nodes in your swarm
docker-machine ssh myvm1 "docker node inspect <node ID>"        # Inspect a node
docker-machine ssh myvm1 "docker swarm join-token -q worker"   # View join token
docker-machine ssh myvm1   # Open an SSH session with the VM; type "exit" to end
docker-machine ssh myvm2 "docker swarm leave"  # Make the worker leave the swarm
docker-machine ssh myvm1 "docker swarm leave -f" # Make master leave, kill swarm
docker-machine start myvm1            # Start a VM that is currently not running
docker-machine stop $(docker-machine ls -q)               # Stop all running VMs
docker-machine rm $(docker-machine ls -q) # Delete all VMs and their disk images
docker-machine scp docker-compose.yml myvm1:~     # Copy file to node's home dir
docker-machine ssh myvm1 "docker stack deploy -c <file> <app>"   # Deploy an app

 Estimated reading time:  7 minutes 

version: "3"
services:
  web:
    image: username/repo:tag
    deploy:
      replicas: 5
      restart_policy:
        condition: on-failure
      resources:
        limits:
          cpus: "0.1"
          memory: 50M
    ports:
      - "80:80"
    networks:
      - webnet
  visualizer:
    image: dockersamples/visualizer:stable
    ports:
      - "8080:8080"
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock"
    deploy:
      placement:
        constraints: [node.role == manager]
    networks:
      - webnet
networks:
  webnet:

docker-machine scp docker-compose.yml myvm1:~

$ docker-machine ssh myvm1 "docker stack deploy -c docker-compose.yml getstartedlab"
Updating service getstartedlab_web (id: angi1bf5e4to03qu9f93trnxm)
Updating service getstartedlab_visualizer (id: l9mnwkeq2jiononb5ihz9u7a4)

docker-machine ssh myvm1 "docker stack ps getstartedlab"

version: "3"
services:
  web:
    image: username/repo:tag
    deploy:
      replicas: 5
      restart_policy:
        condition: on-failure
      resources:
        limits:
          cpus: "0.1"
          memory: 50M
    ports:
      - "80:80"
    networks:
      - webnet
  visualizer:
    image: dockersamples/visualizer:stable
    ports:
      - "8080:8080"
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock"
    deploy:
      placement:
        constraints: [node.role == manager]
    networks:
      - webnet
  redis:
    image: redis
    ports:
      - "6379:6739"
    volumes:
      - ./data:/data
    deploy:
      placement:
        constraints: [node.role == manager]
    networks:
      - webnet
networks:
  webnet:

$ docker-machine ssh myvm1 "mkdir ./data"
$ docker-machine scp docker-compose.yml myvm1:~
$ docker-machine ssh myvm1 "docker stack deploy -c docker-compose.yml getstartedlab"

Get Started, Part 6: Deploy your app

Estimated reading time: 6 minutes

• 1: Orientation
• 2: Containers
• 3: Services
• 4: Swarms
• 5: Stacks
• 6: Deploy your app

Prerequisites

• Install Docker version 1.13 or higher.
• Read the orientation in Part 1.
• Learn how to create containers in Part 2.
• Make sure you have pushed the container you created to a registry, as instructed; we’ll be using it here.
• Ensure your image is working by running this and visiting http://localhost/ (slotting in your info for username, repo, and tag):

  docker run -p 80:80 username/repo:tag
  

• Have the final version of docker-compose.yml from Part 5 handy.

Introduction

You’ve been editing the same Compose file for this entire tutorial. Well, we have good news: that Compose file works just as well in production as it does on your machine. Here, we go through some options for running your Dockerized application.

Choose an option

• Docker CE (Cloud provider)
• Enterprise (Cloud provider)
• Enterprise (On-premise)

docker stack deploy -c docker-compose.yml getstartedlab

Congratulations!

You’ve taken a full-stack, dev-to-deploy tour of the entire Docker platform.

There is much more to the Docker platform than what was covered here, but you have a good idea of the basics of containers, images, services, swarms, stacks, scaling, load-balancing, volumes, and placement constraints.

Want to go deeper? Here are some resources we recommend:

• Samples: Our samples include multiple examples of popular software running in containers, and some good labs that teach best practices.
• User Guide: The user guide has several examples that explain networking and storage in greater depth than was covered here.
• Admin Guide: Covers how to manage a Dockerized production environment.
• Training: Official Docker courses that offer in-person instruction and virtual classroom environments.
• Blog: Covers what’s going on with Docker lately.