docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Fix for 404 bg object, right-nav

This commit is contained in:
John Mulhausen 2016-10-11 01:00:32 -07:00
parent 6b2de29fa7
commit d9701c4b51
6 changed files with 157 additions and 117 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
css/documentation.css
View File

@ -336,7 +336,6 @@ color: #F04124;
border: 0;
text-indent: -9999px;
background-color: transparent;
background-image: url("https://blog.docker.com/wp-content/themes/whale_roots/assets/img/search-icon.png");
/* background-size: 38px 38px; */
background-repeat: no-repeat;
background-position: center center;

22
getting-started/index.md
View File

@ -10,24 +10,19 @@ title: "Getting Started, Part 1: Orientation and Setup"
This tutorial will create a simple application that runs in a cluster, so you
get a sense of how to build distributed applications with the Docker platform.
We will achieve this in the following steps:
1. In part one, which you're reading now, we get set up and oriented.
2. In part two, we create a "Hello World" application that identifies itself.
3. In part three, we hook up a visitor counter.
4. In part four, we show how to scale this "Hello World" app as if it were very
high traffic, by setting up a cluster.
5. In part five, we show how to manage our cluster with a graphical user
interface tool, and roll out code updates.
1. Get set up and oriented, on this page.
2. [Create a "Hello World" application that identifies its environment](part2.md)
3. [Hook up a visitor counter](part3.md)
4. [Scale our app as if it were very high traffic, by setting up a cluster in
production](part4.md)
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.
By the end of this tutorial, you should have a good sense of how the entire
platform works, from setting up your dev environment, running and testing your
code, and finally, building, deploying, and managing your application.
## Setup
Before we get started, make sure your system has the latest version of Docker
@ -35,6 +30,11 @@ installed.
[Install Docker](/engine/installation/index.md){: class="button darkblue-btn"}
> Note: If you're in Linux, you'll want to install
[Docker Toolbox](../toolbox/index.md) so you get Docker Compose.
## Let's go!
If you understand that container images package application code and their
dependencies all together in a portable deliverable, and your environment has
Docker installed, let's move on!

142
getting-started/part2.md
View File

@ -13,26 +13,28 @@ In this section, you will write, build, run, and share an app, the Docker way.
## Your development environment
Normally if you were to start writing a Python app on your laptop, your first
order of business would be 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.
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.
In Docker, you can just grab an image of Python runtime that is already set up,
and use that as a base for creating your app. Then, your build can include the
base Python image right alongside your app code, ensuring that your app and the
runtime it needs to run all travel together.
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.
It's done with something called a Dockerfile.
These builds are configured with something called a `Dockerfile`.
## Your first Dockerfile
Create a folder and put this file in it, with the name `Dockerfile` (no
extension). This Dockerfile defines what goes on in the environment inside your
container. Things are virtualized inside this environment, which is isolated
from the rest of your system, so you have to map ports to the outside world, and
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 with this
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 %}
@ -41,34 +43,30 @@ 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:
- Go get the base Python 2.7 runtime
- 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 my current directory (on my machine) into `/app` (in this container image)
- Install any Python packages that I list inside what is now `/app/requirements.txt` inside the container
- Ensure that this container has port 80 open when it runs
- 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, when the container runs, execute `python` and pass in what is now `/app/app.py`
This paradigm is how developing with Docker essentially works. Make a
`Dockerfile` that includes the base image, grabs your code, installs
dependencies, initializes variables, and runs the command.
- Finally, execute `python` and pass in `app.py` as the "entry point" command,
the default command that is executed at runtime.
### The app itself
Grab these two files that were referred to in the above `Dockerfile` and place
them together with `Dockerfile`, all in the same folder.
Grab these two files and place them in the same folder as `Dockerfile`.
{% gist johndmulhausen/074cc7f4c26a9a8f9164b20b22602ad7 %}
{% gist johndmulhausen/8728902faede400c057f3205392bb9a8 %}
You're probably getting the picture by now. In `Dockerfile` we told the `pip`
package installer to install whatever was in `requirements.txt`, which we
now see is the Flask and Redis libraries for Python. The app itself is going to
print the environment variable of `NAME`, which we set as `World`, as well as
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. Finally, because Redis isn't running
(we've only installed the Python library), we should expect that the attempt to
use it here will fail and show the error message.
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.
## Build the App
@ -77,8 +75,7 @@ That's it! You don't need to have installed Python or anything 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.
Make sure you're in the directory where you saved the three files we've shown,
and you've got everything.
7Here's what `ls` should show:
```shell
$ ls
@ -86,15 +83,13 @@ 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, which you can use interchangeable
with the image ID in commands.
tag using `-t` so it has a friendly name.
```shell
docker build -t "friendlyhello" .
docker build -t friendlyhello .
```
In the output spew you can see everything defined in the `Dockerfile` happening,
including the installation of the packages we specified in `requirements.txt`.
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:
@ -106,22 +101,25 @@ friendlyhello latest 326387cea398 47 seconds ago
## Run the app
We're going to run the app and route traffic from our machine's port 80 to the
port 80 we exposed
Run the app, mapping our machine's port 4000 to the container's exposed port 80
using `-p`:
```shell
docker run -p 80:80 friendlyhello
docker run -p 4000:80 friendlyhello
```
You should see a notice that Python is serving your app at `http://0.0.0.0:80`.
You can go there, or just to `http://localhost`, and see your app, "Hello World"
text, the container ID, and the Redis error message, all printed out in
beautiful Times New Roman.
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` and let's run the app in the background, in detached mode.
Hit `CTRL+C` in your terminal to quit.
Now let's run the app in the background, in detached mode:
```shell
docker run -d -p 80:80 friendlyhello
docker run -d -p 4000:80 friendlyhello
```
You get a hash ID of the container instance and then are kicked back to your
@ -133,25 +131,22 @@ CONTAINER ID IMAGE COMMAND CREATED
1fa4ab2cf395 friendlyhello "python app.py" 28 seconds ago Up 25 seconds
```
You'll see that `CONTAINER ID` matches what's on `http://localhost`, if you
refresh the browser page. You can't `CTRL+C` now, so let's kill the process this
way. Use the value you see under `CONTAINER ID`:
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:
```shell
docker kill (containerID)
docker stop 1fa4ab2cf395
```
## Share the App
## Share your image
Now let's test how portable this app really is.
Sign up for Docker Hub at [https://hub.docker.com/](https://hub.docker.com/).
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 assets associated
with your account - like a GitHub repository, except the code is already built.
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.
@ -187,9 +182,40 @@ and run this command:
docker run YOURUSERNAME/YOURREPO:ARBITRARYTAG
```
> Note: If you don't specify the `:ARBITRARYTAG` portion of these commands,
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.
## Recap and cheat sheet for images and containers
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.
```shell
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"}

88
getting-started/part3.md
View File

@ -9,8 +9,8 @@ wrote, built, ran, and shared our first Dockerized app, which all fit in a
single container.
In part 3, we will expand this application so that it is comprised of two
containers simultaneously: one running the web app we have already written, and
another that stores data on the web app's behalf.
containers running simultaneously: one running the web app we have already
written, and another that stores data on the web app's behalf.
## Understanding services
@ -28,24 +28,23 @@ and that's going to happen via a different executable entirely.
In a distributed application, these different pieces of the app are called
"services." For example, if you imagine a video sharing site, there will
probably be a service for storing application data in a database, another one
probably be a service for storing application data in a database, a service
for video transcoding in the background after a user uploads something, a
service for streaming, and so on, and they all need to work in concert.
service for the front-end, and so on, and they all need to work in concert.
The easiest way to introduce the organization of your app into services using
containers is by using Docker Compose. We're going to add a data storage service
The easiest way to organize your containerized app into services using
is using Docker Compose. We're going to add a data storage service
to our simple Hello World app. Don't worry, it's shockingly easy.
## Your first `docker-compose.yml` File
As you saw, a `Dockerfile` is a text file that defines a single Docker image.
But a `docker-compose.yml` file is a YAML markup file that is hierarchical in
A `docker-compose.yml` file is a YAML markup file that is hierarchical in
structure, and defines how multiple Docker images should work together when
they are running in containers.
We saw that the "Hello World" app we created looked for a running instance of
Redis, and if it failed, it produced an error message. All we need is a running
Redis instance, and that error message will be replaced with a visitor counter.
Redis instance, and that error message will be replaced with a visitor counter.
Well, just as we grabbed the base image of Python earlier, we can grab the
official image of Redis, and run that right alongside our app.
@ -63,14 +62,14 @@ image](https://store.docker.com/images/1f6ef28b-3e48-4da1-b838-5bd8710a2053)).
This `docker-compose.yml` file tells Docker to do the following:
- Pull and run [the image we uploaded in step 2](/getting-started/part2/#/share-the-app) as a service called `web`
- Map port 80 on the host to the container's port 80 (so http://localhost:80 resolves properly)
- Link this container to the service we named `redis`; this ensures that the
dependency between `redis` and `web` is expressed, as well as the order of service
startup.
- Pull and run the official Redis image as a service called `redis`
- Pull and run [the image we uploaded to Docker Hub in step 2](/getting-started/part2/#/share-the-app) as a service called `web`
- Map port 4000 on the host to `web`'s port 80
- Link the `web` service to the service we named `redis`; this ensures that the
dependency between `redis` and `web` is expressed, and these containers will
run together in the same subnet.
- Our service named `redis` just runs the official Redis image, so go get it from Docker Hub.
## Run your first multi-container app
## Run and scale up your first multi-container app
Run this command in the directory where you saved `docker-compose.yml`:
@ -79,52 +78,63 @@ docker-compose up
```
This will pull all the necessary images and run them in concert. Now when you
visit `http://localhost`, you'll see a number next to the visitor counter
visit `http://localhost:4000`, you'll see a number next to the visitor counter
instead of the error message. It really works -- just keep hitting refresh.
## Connecting to this instance of Redis
## Connecting to containers with port mapping
With a containerized instance of Redis running, you're probably wondering --
how do I break through the wall of isolation and manage my data? The answer is,
port mapping. [The page for the official Redis
image](https://store.docker.com/images/1f6ef28b-3e48-4da1-b838-5bd8710a2053)
states that the normal management ports are open in their image, so you should
states that the normal management ports are open in their image, so you would
be able to connect to it at `localhost:6379` if you add a `ports:` section to
`docker-compose.yml` under `redis` that maps `6379` to your host, just as port
`80` is mapped for `web`. Same with MySQL or any other data solution;
containerized doesn't mean unreachable, it just means portable. Once you map
your ports, you can use your fave UI tools like MySQL Workbench, Redis Desktop
Manager, etc, to connect to your Dockerized instance.
`80` is mapped for `web`. Same with MySQL or any other data solution; once you
map your ports, you can use your fave UI tools like MySQL Workbench, Redis
Desktop Manager, etc, to connect to your Dockerized instance.
Redis port mapping isn't necessary in `docker-compose.yml` because the two
services (`web` and `redis`) are linked, ensuring they run on the same host (VM
or physical machine). Within that host, the containers can talk to each other
in a private subnet that is automatically created by the Docker runtime, which
isn't accessible to the outside world, only to other containers. In our app,
we specify `EXPOSE 80` in our Dockerfile, and as you can see in the Redis
documentation, they specify `EXPOSE 6379` in the Dockerfile that defines the
official Redis image. But those ports aren't accessible outside of the private
subnet (or, in turn, reachable at `http://localhost`) until you map the host's
port 80 to the container's port 80, which is why we specified as much in
`docker run` previously, and `docker-compose.yml` just now.
services (`web` and `redis`) are linked, ensuring they run on the same host (VM
or physical machine), in a private subnet that is automatically created by the
Docker runtime. Containers within
that subnet can already talk to each other; it's connecting from the outside
that necessitates port mapping.
## Cheat sheet and recap: Hosts, subnets, and Docker Compose
You learned that by creating a `docker-compose.yml` file, you can define the
entire stack for your application. This ensures that your services run
together in a private subnet that lets them connect to each
other, but only to the world as specifically dircted. This means that if you
want to connect your favorite data management software to your data storage
service, you'll have to ensure the container has the proper port exposed and
your host has that port mapped to the container in `docker-compose.yml`.
```shell
docker-compose up #Pull and run images specified in `docker-compose.yml` as services
docker-compose up -d #Same thing, but in background mode
docker-compose stop #Stop all running containers for this app
docker-compose rm -f #Remove all containers for this app
```
## Get ready to scale
Until now, I've been able to shield you from worrying too much about host
management. That's because installing Docker always sets up a default way
to run containers in a single-host environment. Docker for Windows and Mac
to run containers on that machine. Docker for Windows and Mac
comes with a virtual machine host running a lighweight operating system
we call Moby, which is just a very slimmed-down Linux. Docker for Linux
just works without a VM at all. And Docker for Windows can run Microsoft
we call Moby, which is just a very slimmed-down Linux. Docker for Linux
just works without a VM at all. And Docker for Windows can even run Microsoft
Windows containers using native Hyper-V support. When you've run `docker
run` and `docker-compose up` so far, Docker has used these default hosts
run` and `docker-compose up` so far, Docker has used these solutions
to run your containers. That's because we want you to be able to install
Docker and get straight to the work of development and building images.
But when it comes to getting your app into production, we all know that
you're not going to run just one host machine that has Redis, Python, and
all your other sevices. That won't scale. You need to learn how to run not
just multiple containers on one host, but multiple containers on multiple
hosts. And that's precisely what we're going to get into next.
just multiple containers on your local host, but multiple containers on
multiple hosts. And that's precisely what we're going to get into next.
[On to "Part 4: Running our App in Production" >>](part4.md){: class="button darkblue-btn"}

15
getting-started/part4.md
View File

@ -98,15 +98,18 @@ into a swarm.
## Creating your first Swarm cluster
1. Go back to Docker Cloud by visiting [cloud.docker.com](https://cloud.docker.com).
2. Click **Node Clusters** in the left-navigation, then click the **Create** button.
2. Click **Node Clusters** in the left navigation, then click the **Create** button.
This pulls up a form where you can create our cluster.
3. Leave everything default, except:
- Name: Give your cluster a name.
- Region: Select a region that's close to you.
- Name: Give your cluster a name
- Region: Select a region that's close to you
- Provider: Set to "Amazon Web Services"
- Type/Size:
4. Launch the cluster by clicking **Launch node cluster**, and
5.
- Type/Size: Select the `t2.nano` option as that is free-tier
4. Launch the cluster by clicking **Launch node cluster**; this will spin
up a free-tier Amazon instance.
5. Now, click **Services** in the left navigation, then the **Create** button,
then the **globe icon**.
6. Search Docker Hub for the image you uploaded
[On to next >>](part5.md){: class="button darkblue-btn"}

6
js/menu.js
View File

@ -54,8 +54,8 @@ jQuery(document).ready(function(){
var index = 0;
var currentHeader = 0, lastHeader = 0;
var output = "";
$("h2, h3, h4").each(function() {
var output = "<ul>";
$("h1, h2, h3, h4").each(function() {
var li= "<li><a href='" + window.location + "#" + $(this).attr('id') + "'>" + $(this).text().replace("¶","") + "</a></li>";
if( $(this).is("h2") ){
// h2
@ -67,12 +67,14 @@ jQuery(document).ready(function(){
// h4
currentHeader = 4;
}
console.log("currentHeader ",currentHeader, "lastHeader ",lastHeader, "text ", $(this).text());
if (currentHeader > lastHeader) {
// nest further
output += "<ul>"
}
if (currentHeader < lastHeader && lastHeader > 0) {
// close nesting
console.log("Closing nesting because ", lastHeader, "is <", currentHeader);
for (i=0; i < (lastHeader - currentHeader); i++)
{
output += "</ul>"