title: "Getting Started, Part 2: Creating and Building Your App"

In [Getting Started, Part 1: Orientation and Setup](index.md), you heard an

overview of what containers are, what the

Docker platform does, and what we'll be covering in this multi-part tutorial.

You also got Docker installed on your machine.

In this section, you will write, build, run, and share an app, the Docker way.

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 builds are configured with something called a `Dockerfile`.

Create an empty directory and put this file in it, with the name `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.

{% gist johndmulhausen/c31813e076827178216b74e6a6f4a087 %}

This `Dockerfile` refers to a couple of things we haven't created yet, namely

`app.py` and `requirements.txt`. We'll get there. But here's what this

`Dockerfile` is saying:

- Download the official image of the Python 2.7 runtime and include it here.

- Create `/app` and set it as the current working directory inside the container

- Copy the contents of the current directory on my machine into `/app` inside the container

- Install any Python packages that I list inside `requirements.txt`

- Ensure that port 80 is exposed to the world outside this container

- Set an environment variable within this container named `NAME` to be the string `World`

- Finally, execute `python` and pass in `app.py` as the "entry point" command,

the default command that is executed at runtime.

Grab these two files and place them in the same folder as `Dockerfile`.

{% gist johndmulhausen/074cc7f4c26a9a8f9164b20b22602ad7 %}

{% gist johndmulhausen/8728902faede400c057f3205392bb9a8 %}

Now we see that the `Dockerfile` command `pip install requirements.txt` installs

the Flask and Redis libraries for Python. We can also see that app itself

prints the environment variable of `NAME`, which we set as `World`, as well as

the output of a call to `socket.gethostname()`, which the Docker runtime is

going to answer with the container ID, which is sort of like the process ID for

an executable. 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.

That's it! You don't need to have installed Python or anything in

`requirements.txt` on your system, nor will running this app install them in

your system. It doesn't seem like you've really set up an environment with

Python and Flask, but you have. Let's build and run your app and prove it.

7Here'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 .

In the output spew you can see everything defined in the `Dockerfile` happening.

Where is your built image? It's in your machine's local Docker image registry.

Check it out:

$ docker images

REPOSITORY TAG IMAGE ID CREATED SIZE

friendlyhello latest 326387cea398 47 seconds ago 192.1 MB

Run the app, mapping our 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

actually want to access your app at: `http://localhost:4000`. Go there, and

you'll see the "Hello World" text, the container ID, and the Redis error

message, all printed out in beautiful Times New Roman.

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 a hash ID of the container instance and then are kicked back to your

terminal. Your app is running in the background. Let's see it with `docker ps`:

$ docker ps

CONTAINER ID IMAGE COMMAND CREATED STATUS

1fa4ab2cf395 friendlyhello "python app.py" 28 seconds ago Up 25 seconds

You'll see that `CONTAINER ID` matches what's on `http://localhost:4000`, if you

refresh the browser page. Now use `docker stop` to end the process, using

`CONTAINER ID`, like so:

docker stop 1fa4ab2cf395

Sign up a Docker account at [hub.docker.com](https://hub.docker.com/).

Make note of your username. We're going to use it in a couple commands.

Docker Hub is a public registry. A registry is a collection of accounts and

their various repositories. A repository is a collection of tagged images like a

GitHub repository, except the code is already built.

Log in your local machine to Docker Hub.

docker login

Now, let's publish your image. First, specify the repository you'd like to use

in a tag. 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 mechnism that registries use to give Docker images a version. So,

putting all that together:

docker tag friendlyhello YOURUSERNAME/YOURREPO:ARBITRARYTAG

From now on, you can use `docker run` on this machine with the fully qualified

tag. But that won't work on other machines until you upload this image, like so:

docker push YOURUSERNAME/YOURREPO:ARBITRARYTAG

Once complete, the results of this upload are [publicly available

on Docker Hub](https://hub.docker.com/).

Now, remembering whatever you specified as your target repo, and whatever you

used as a tag, go on another machine. Any machine where you can install Docker,

and run this command:

docker run YOURUSERNAME/YOURREPO:ARBITRARYTAG

the tag of `:latest` will be assumed, both when you build and when you run

images.

You'll see this stranger of a machine pull your image, along with Python and all

the dependencies from `requirements.txt`, and run your code. It all travels

together in a neat little package, and the new machine didn't have to install

anything but Docker to run it.

To recap: After calling `docker run`, you created and ran a container, based on

the image created when you called `docker build`. Images are defined in a

`Dockerfile`. A container is an instance of an image, and it has any package

installations, file writes, etc that happen after you call `docker run` and run

the app. And lastly, images are shared via a registry.

docker build -t friendlyname . #Create image using this directory's Dockerfile

docker run -p 4000:80 friendlyname #Run image "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 on this machine, 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 that have been built or downloaded onto 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 (to Docker Hub by default)

docker tag <image> username/repository:tag #Tag <image> on your local machine for upload

docker push username/repository:tag #Upload tagged image to registry (Docker Hub by default)

docker run username/repository:tag #Run image from a registry (Docker Hub by default)

[On to "Getting Started, Part 3: Stateful, Multi-container Applications" >>](part3.md){: class="button darkblue-btn"}