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

Get started docs updates (#10218) 

* Update Get started docs

* update part-1, add redirects

* draft updates to part 2 and 3

* tidy up the orchestration topics

* update examples, and other minor edits

* address Stefan's review comments

* moved orchestration to a new node

* fix Ben's review comments

* add email verification step

* Emphasize the CTA in part 3
This commit is contained in:
Usha Mandya 2020-02-14 17:24:50 +00:00 committed by GitHub
parent 4e2143de9e
commit 36aba6a7c6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
10 changed files with 713 additions and 575 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
_data/toc.yaml
View File

@ -27,14 +27,10 @@ guides:
section:
- title: "Part 1: Orientation and setup"
path: /get-started/
- title: "Part 2: Containerizing an application"
- title: "Part 2: Build and run your image"
path: /get-started/part2/
- title: "Part 3: Deploying to Kubernetes"
- title: "Part 3: Share images on Docker Hub"
path: /get-started/part3/
- title: "Part 4: Deploying to Swarm"
path: /get-started/part4/
- title: "Part 5: Sharing images on Docker Hub"
path: /get-started/part5/
- path: /get-started/resources/
title: "Educational resources"
- sectiontitle: Develop with Docker
@ -129,6 +125,14 @@ guides:
title: Use the VFS storage driver
- sectiontitle: Run your app in production
section:
- sectiontitle: Orchestration
section:
- title: "Overview"
path: /get-started/orchestration/
- title: "Deploy to Kubernetes"
path: /get-started/kube-deploy/
- title: "Deploy to Swarm"
path: /get-started/swarm-deploy/
- sectiontitle: Configure all objects
section:
- path: /config/labels-custom-metadata/

13
develop/index.md
View File

@ -4,7 +4,11 @@ description: Overview of developer resources
keywords: developer, developing, apps, api, sdk
---
This page lists resources for application developers using Docker.
This page contains a list of resources for application developers who would like to build new applications using Docker.
## Prerequisites
Work through the learning modules in [Get started](/get-started/index.md) to understand how to build an image and run it as a containerized application.
## Develop new apps on Docker
@ -12,12 +16,11 @@ If you're just getting started developing a brand new app on Docker, check out
these resources to understand some of the most common patterns for getting the
most benefits from Docker.
- Learn to [build an image from a Dockerfile](/get-started/part2.md){: target="_blank" class="_"}
- Use [multistage builds](/engine/userguide/eng-image/multistage-build.md){: target="_blank" class="_"} to keep your images lean
- Manage application data using [volumes](/engine/admin/volumes/volumes.md) and [bind mounts](/engine/admin/volumes/bind-mounts.md){: target="_blank" class="_"}
- [Scale your app](/get-started/part3.md){: target="_blank" class="_"} with kubernetes
- [Scale your app](/get-started/part4.md){: target="_blank" class="_"} as a swarm service
- General application development best practices
- [Scale your app](/get-started/kube-deploy.md){: target="_blank" class="_"} with kubernetes
- [Scale your app](/get-started/swarm-deploy.md){: target="_blank" class="_"} as a swarm service
- [General application development best practices](/develop/dev-best-practices.md){: target="_blank" class="_"}
## Learn about language-specific app development with Docker

390
get-started/index.md
View File

@ -57,44 +57,38 @@ redirect_from:
{% include_relative nav.html selected="1" %}
Welcome! We are excited that you want to learn Docker. The _Docker Community QuickStart_
teaches you how to:
Welcome! We are excited that you want to learn Docker. The Docker Quickstart training module teaches you how to:
1. Set up your Docker environment (on this page)
2. [Build an image and run it as one container](part2.md)
3. [Set up and use a Kubernetes environment on your development machine](part3.md)
4. [Set up and use a Swarm environment on your development machine](part4.md)
5. [Share your containerized applications on Docker Hub](part5.md)
2. [Build and run your image](part2.md)
3. [Share images on Docker Hub](part3.md)
## Docker concepts
Docker is a platform for developers and sysadmins to **build, share, and run**
Docker is a platform for developers and sysadmins to **build, run, and share**
applications with containers. The use of containers to deploy applications
is called _containerization_. Containers are not new, but their use for easily
deploying applications is.
Containerization is increasingly popular because containers are:
- Flexible: Even the most complex applications can be containerized.
- Lightweight: Containers leverage and share the host kernel,
- **Flexible**: Even the most complex applications can be containerized.
- **Lightweight**: Containers leverage and share the host kernel,
making them much more efficient in terms of system resources than virtual machines.
- Portable: You can build locally, deploy to the cloud, and run anywhere.
- Loosely coupled: Containers are highly self sufficient and encapsulated,
- **Portable**: You can build locally, deploy to the cloud, and run anywhere.
- **Loosely coupled**: Containers are highly self sufficient and encapsulated,
allowing you to replace or upgrade one without disrupting others.
- Scalable: You can increase and automatically distribute container replicas across a datacenter.
- Secure: Containers apply aggressive constraints and isolations to processes without
any configuration required on the part of the user.
![Containers are portable](images/laurel-docker-containers2019.png){:width="100%"}
- **Scalable**: You can increase and automatically distribute container replicas across a datacenter.
- **Secure**: Containers apply aggressive constraints and isolations to processes without any configuration required on the part of the user.
### Images and containers
Fundamentally, a container is nothing but a running process,
with some added encapsulation features applied to it in order to keep it isolated from the host
and from other containers.
One of the most important aspects of container isolation is that each container interacts
with its own, private filesystem; this filesystem is provided by a Docker **image**.
An image includes everything needed to run an application -- the code or binary,
with some added encapsulation features applied to it in order to keep it isolated from the host and from other containers.
One of the most important aspects of container isolation is that each container interacts with its own private filesystem; this filesystem is provided by a Docker **image**.
An image includes everything needed to run an application - the code or binary,
runtimes, dependencies, and any other filesystem objects required.
### Containers and virtual machines
@ -109,342 +103,66 @@ VMs incur a lot of overhead beyond what is being consumed by your application lo
![Container stack example](/images/Container%402x.png){:width="300px"} | ![Virtual machine stack example](/images/VM%402x.png){:width="300px"}
### Orchestration
## Set up your Docker environment
The portability and reproducibility of a containerized process mean we have
an opportunity to move and scale our containerized applications across
clouds and datacenters; containers effectively guarantee that those
applications will run the same way anywhere, allowing us to quickly and
easily take advantage of all these environments.
Furthermore, as we scale our applications up, we'll
want some tooling to help automate the maintenance of those applications,
able to replace failed containers automatically and manage the rollout of updates
and reconfigurations of those containers during their lifecycle.
### Download and install Docker Desktop
Tools to manage, scale, and maintain containerized applications are called
_orchestrators_, and the most common examples of these are _Kubernetes_ and
_Docker Swarm_. Development environment deployments of both of these
orchestrators are provided by Docker Desktop, which we'll use throughout
this guide to create our first orchestrated, containerized application.
Docker Desktop is an easy-to-install application for your Mac or Windows environment that enables you to start coding and containerizing in minutes. Docker Desktop includes everything you need to build, run, and share containerized applications right from your machine.
## Install Docker Desktop
Follow the instructions appropriate for your operating system to download and install Docker Desktop:
The best way to get started developing containerized applications is with Docker Desktop, for OSX or Windows. Docker Desktop will allow you to easily set up Kubernetes or Swarm on your local development machine, so you can use all the features of the orchestrator you're developing applications for right away, no cluster required. Follow the installation instructions appropriate for your operating system:
- [Docker Desktop for Mac](/docker-for-mac/install/){: target="_blank" class="_"}
- [Docker Desktop for Windows](/docker-for-windows/install/){: target="_blank" class="_"}
- [OSX](/docker-for-mac/install/){: target="_blank" class="_"}
- [Windows](/docker-for-windows/install/){: target="_blank" class="_"}
### Test Docker version
## Enable Kubernetes
After you've successfully installed Docker Desktop, open a terminal and run `docker --version` to check the version of Docker installed on your machine.
Docker Desktop will set up Kubernetes for you quickly and easily. Follow the setup and validation instructions appropriate for your operating system:
```shell
$ docker --version
Docker version 19.03.5, build 633a0ea
```
<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" href="#kubeosx">OSX</a></li>
<li><a data-toggle="tab" href="#kubewin">Windows</a></li>
</ul>
<div class="tab-content">
<div id="kubeosx" class="tab-pane fade in active">
{% capture local-content %}
### Test Docker installation
#### OSX
1. After installing Docker Desktop, you should see a Docker icon in your menu bar. Click on it, and navigate **Preferences... -> Kubernetes**.
2. Check the checkbox labeled *Enable Kubernetes*, and click **Apply**. Docker Desktop will automatically set up Kubernetes for you. You'll know everything has completed successfully once you can click on the Docker icon in the menu bar, and see a green light beside 'Kubernetes is Running'.
3. In order to confirm that Kubernetes is up and running, create a text file called `pod.yaml` with the following content:
```yaml
apiVersion: v1
kind: Pod
metadata:
name: demo
spec:
containers:
- name: testpod
image: alpine:3.5
command: ["ping", "8.8.8.8"]
```
This describes a pod with a single container, isolating a simple ping to 8.8.8.8.
4. In a terminal, navigate to where you created `pod.yaml` and create your pod:
1. Test that your installation works by running the [hello-world](https://hub.docker.com/_/hello-world/){: target="_blank" class="_"} Docker image:
```shell
kubectl apply -f pod.yaml
$ docker run hello-world
Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
ca4f61b1923c: Pull complete
Digest: sha256:ca0eeb6fb05351dfc8759c20733c91def84cb8007aa89a5bf606bc8b315b9fc7
Status: Downloaded newer image for hello-world:latest
Hello from Docker!
This message shows that your installation appears to be working correctly.
...
```
5. Check that your pod is up and running:
2. Run `docker image ls` to list the `hello-world` image that you downloaded to your machine.
3. List the `hello-world` container (spawned by the image) which exits after displaying its message. If it is still running, you do not need the `--all` option:
```shell
kubectl get pods
$ docker container ls --all
CONTAINER ID IMAGE COMMAND CREATED STATUS
54f4984ed6a8 hello-world "/hello" 20 seconds ago Exited (0) 19 seconds ago
```
You should see something like:
```shell
NAME READY STATUS RESTARTS AGE
demo 1/1 Running 0 4s
```
6. Check that you get the logs you'd expect for a ping process:
```shell
kubectl logs demo
```
You should see the output of a healthy ping process:
```shell
PING 8.8.8.8 (8.8.8.8): 56 data bytes
64 bytes from 8.8.8.8: seq=0 ttl=37 time=21.393 ms
64 bytes from 8.8.8.8: seq=1 ttl=37 time=15.320 ms
64 bytes from 8.8.8.8: seq=2 ttl=37 time=11.111 ms
...
```
7. Finally, tear down your test pod:
```shell
kubectl delete -f pod.yaml
```
{% endcapture %}
{{ local-content | markdownify }}
</div>
<div id="kubewin" class="tab-pane fade" markdown="1">
{% capture localwin-content %}
#### Windows
1. After installing Docker Desktop, you should see a Docker icon in your system tray. Right-click on it, and navigate **Settings -> Kubernetes**.
2. Check the checkbox labeled *Enable Kubernetes*, and click **Apply**. Docker Desktop will automatically set up Kubernetes for you. Note this can take a significant amount of time (20 minutes). You'll know everything has completed successfully once you can right-click on the Docker icon in the menu bar, click **Settings**, and see a green light beside 'Kubernetes is running'.
3. In order to confirm that Kubernetes is up and running, create a text file called `pod.yaml` with the following content:
```yaml
apiVersion: v1
kind: Pod
metadata:
name: demo
spec:
containers:
- name: testpod
image: alpine:3.5
command: ["ping", "8.8.8.8"]
```
This describes a pod with a single container, isolating a simple ping to 8.8.8.8.
4. In powershell, navigate to where you created `pod.yaml` and create your pod:
```shell
kubectl apply -f pod.yaml
```
5. Check that your pod is up and running:
```shell
kubectl get pods
```
You should see something like:
```shell
NAME READY STATUS RESTARTS AGE
demo 1/1 Running 0 4s
```
6. Check that you get the logs you'd expect for a ping process:
```shell
kubectl logs demo
```
You should see the output of a healthy ping process:
```shell
PING 8.8.8.8 (8.8.8.8): 56 data bytes
64 bytes from 8.8.8.8: seq=0 ttl=37 time=21.393 ms
64 bytes from 8.8.8.8: seq=1 ttl=37 time=15.320 ms
64 bytes from 8.8.8.8: seq=2 ttl=37 time=11.111 ms
...
```
7. Finally, tear down your test pod:
```shell
kubectl delete -f pod.yaml
```
{% endcapture %}
{{ localwin-content | markdownify }}
</div>
<hr>
</div>
## Enable Docker Swarm
Docker Desktop runs primarily on Docker Engine, which has everything you need to run a Swarm built in. Follow the setup and validation instructions appropriate for your operating system:
<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" href="#swarmosx">OSX</a></li>
<li><a data-toggle="tab" href="#swarmwin">Windows</a></li>
</ul>
<div class="tab-content">
<div id="swarmosx" class="tab-pane fade in active">
{% capture local-content %}
#### OSX
1. Open a terminal, and initialize Docker Swarm mode:
```shell
docker swarm init
```
If all goes well, you should see a message similar to the following:
```shell
Swarm initialized: current node (tjjggogqpnpj2phbfbz8jd5oq) is now a manager.
To add a worker to this swarm, run the following command:
docker swarm join --token SWMTKN-1-3e0hh0jd5t4yjg209f4g5qpowbsczfahv2dea9a1ay2l8787cf-2h4ly330d0j917ocvzw30j5x9 192.168.65.3:2377
To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions.
```
2. Run a simple Docker service that uses an alpine-based filesystem, and isolates a ping to 8.8.8.8:
```shell
docker service create --name demo alpine:3.5 ping 8.8.8.8
```
3. Check that your service created one running container:
```shell
docker service ps demo
```
You should see something like:
```shell
ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS
463j2s3y4b5o demo.1 alpine:3.5 docker-desktop Running Running 8 seconds ago
```
4. Check that you get the logs you'd expect for a ping process:
```shell
docker service logs demo
```
You should see the output of a healthy ping process:
```shell
demo.1.463j2s3y4b5o@docker-desktop | PING 8.8.8.8 (8.8.8.8): 56 data bytes
demo.1.463j2s3y4b5o@docker-desktop | 64 bytes from 8.8.8.8: seq=0 ttl=37 time=13.005 ms
demo.1.463j2s3y4b5o@docker-desktop | 64 bytes from 8.8.8.8: seq=1 ttl=37 time=13.847 ms
demo.1.463j2s3y4b5o@docker-desktop | 64 bytes from 8.8.8.8: seq=2 ttl=37 time=41.296 ms
...
```
5. Finally, tear down your test service:
```shell
docker service rm demo
```
{% endcapture %}
{{ local-content | markdownify }}
</div>
<div id="swarmwin" class="tab-pane fade" markdown="1">
{% capture localwin-content %}
#### Windows
1. Open a powershell, and initialize Docker Swarm mode:
```shell
docker swarm init
```
If all goes well, you should see a message similar to the following:
```shell
Swarm initialized: current node (tjjggogqpnpj2phbfbz8jd5oq) is now a manager.
To add a worker to this swarm, run the following command:
docker swarm join --token SWMTKN-1-3e0hh0jd5t4yjg209f4g5qpowbsczfahv2dea9a1ay2l8787cf-2h4ly330d0j917ocvzw30j5x9 192.168.65.3:2377
To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions.
```
2. Run a simple Docker service that uses an alpine-based filesystem, and isolates a ping to 8.8.8.8:
```shell
docker service create --name demo alpine:3.5 ping 8.8.8.8
```
3. Check that your service created one running container:
```shell
docker service ps demo
```
You should see something like:
```shell
ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS
463j2s3y4b5o demo.1 alpine:3.5 docker-desktop Running Running 8 seconds ago
```
4. Check that you get the logs you'd expect for a ping process:
```shell
docker service logs demo
```
You should see the output of a healthy ping process:
```shell
demo.1.463j2s3y4b5o@docker-desktop | PING 8.8.8.8 (8.8.8.8): 56 data bytes
demo.1.463j2s3y4b5o@docker-desktop | 64 bytes from 8.8.8.8: seq=0 ttl=37 time=13.005 ms
demo.1.463j2s3y4b5o@docker-desktop | 64 bytes from 8.8.8.8: seq=1 ttl=37 time=13.847 ms
demo.1.463j2s3y4b5o@docker-desktop | 64 bytes from 8.8.8.8: seq=2 ttl=37 time=41.296 ms
...
```
5. Finally, tear down your test service:
```shell
docker service rm demo
```
{% endcapture %}
{{ localwin-content | markdownify }}
</div>
<hr>
</div>
## Conclusion
At this point, you've installed Docker Desktop on your development machine, and confirmed that you can run simple containerized workloads in Kubernetes and Swarm. In the next section, we'll start developing our first containerized application.
At this point, you've installed Docker Desktop on your development machine, and ran a quick test to ensure you are set up to build and run your first containerized application.
[On to Part 2 >>](part2.md){: class="button outline-btn" style="margin-bottom: 30px; margin-right: 100%"}
## CLI References
## CLI references
Further documentation for all CLI commands used in this article are available here:
Further documentation for all CLI commands used in this article is available here:
- [`kubectl apply`](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#apply)
- [`kubectl get`](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#get)
- [`kubectl logs`](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#logs)
- [`kubectl delete`](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#delete)
- [`docker swarm init`](https://docs.docker.com/engine/reference/commandline/swarm_init/)
- [`docker service *`](https://docs.docker.com/engine/reference/commandline/service/)
- [`docker version`](https://docs.docker.com/engine/reference/commandline/version/)
- [`docker run`](https://docs.docker.com/engine/reference/commandline/run/)
- [`docker image`](https://docs.docker.com/engine/reference/commandline/image/)
- [`docker container`](https://docs.docker.com/engine/reference/commandline/container/)

134
get-started/kube-deploy.md Normal file
View File

@ -0,0 +1,134 @@
---
title: "Deploy to Kubernetes"
keywords: kubernetes, pods, deployments, kubernetes services
description: Learn how to describe and deploy a simple application on Kubernetes.
---
## Prerequisites
- Download and install Docker Desktop as described in [Orientation and setup](/index.md).
- Work through containerizing an application in [Part 2](part2.md).
- Make sure that Kubernetes is enabled on your Docker Desktop:
- **Mac**: Click the Docker icon in your menu bar, navigate to **Preferences** and make sure there's a green light beside 'Kubernetes'.
- **Windows**: Click the Docker icon in the system tray and navigate to **Settings** and make sure there's a green light beside 'Kubernetes'.
If Kubernetes isn't running, follow the instructions in [Orchestration](orchestration.md) of this tutorial to finish setting it up.
## Introduction
Now that we've demonstrated that the individual components of our application run as stand-alone containers, it's time to arrange for them to be managed by an orchestrator like Kubernetes. Kubernetes provides many tools for scaling, networking, securing and maintaining your containerized applications, above and beyond the abilities of containers themselves.
In order to validate that our containerized application works well on Kubernetes, we'll use Docker Desktop's built in Kubernetes environment right on our development machine to deploy our application, before handing it off to run on a full Kubernetes cluster in production. The Kubernetes environment created by Docker Desktop is _fully featured_, meaning it has all the Kubernetes features your app will enjoy on a real cluster, accessible from the convenience of your development machine.
## Describing apps using Kubernetes YAML
All containers in Kubernetes are scheduled as _pods_, which are groups of co-located containers that share some resources. Furthermore, in a realistic application we almost never create individual pods; instead, most of our workloads are scheduled as _deployments_, which are scalable groups of pods maintained automatically by Kubernetes. Lastly, all Kubernetes objects can and should be described in manifests called _Kubernetes YAML_ files. These YAML files describe all the components and configurations of your Kubernetes app, and can be used to easily create and destroy your app in any Kubernetes environment.
1. You already wrote a very basic Kubernetes YAML file in the Orchestration overview part of this tutorial. Now, let's write a slightly more sophisticated YAML file to run and manage our bulletin board. Place the following in a file called `bb.yaml`:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: bb-demo
namespace: default
spec:
replicas: 1
selector:
matchLabels:
bb: web
template:
metadata:
labels:
bb: web
spec:
containers:
- name: bb-site
image: bulletinboard:1.0
---
apiVersion: v1
kind: Service
metadata:
name: bb-entrypoint
namespace: default
spec:
type: NodePort
selector:
bb: web
ports:
- port: 8080
targetPort: 8080
nodePort: 30001
```
In this Kubernetes YAML file, we have two objects, separated by the `---`:
- A `Deployment`, describing a scalable group of identical pods. In this case, you'll get just one `replica`, or copy of your pod, and that pod (which is described under the `template:` key) has just one container in it, based off of your `bulletinboard:1.0` image from the previous step in this tutorial.
- A `NodePort` service, which will route traffic from port 30001 on your host to port 8080 inside the pods it routes to, allowing you to reach your bulletin board from the network.
Also, notice that while Kubernetes YAML can appear long and complicated at first, it almost always follows the same pattern:
- The `apiVersion`, which indicates the Kubernetes API that parses this object
- The `kind` indicating what sort of object this is
- Some `metadata` applying things like names to your objects
- The `spec` specifying all the parameters and configurations of your object.
## Deploy and check your application
1. In a terminal, navigate to where you created `bb.yaml` and deploy your application to Kubernetes:
```shell
kubectl apply -f bb.yaml
```
you should see output that looks like the following, indicating your Kubernetes objects were created successfully:
```shell
deployment.apps/bb-demo created
service/bb-entrypoint created
```
2. Make sure everything worked by listing your deployments:
```shell
kubectl get deployments
```
if all is well, your deployment should be listed as follows:
```shell
NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE
bb-demo 1 1 1 1 48s
```
This indicates all one of the pods you asked for in your YAML are up and running. Do the same check for your services:
```shell
kubectl get services
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
bb-entrypoint NodePort 10.106.145.116 <none> 8080:30001/TCP 53s
kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 138d
```
In addition to the default `kubernetes` service, we see our `bb-entrypoint` service, accepting traffic on port 30001/TCP.
3. Open a browser and visit your bulletin board at `localhost:30001`; you should see your bulletin board, the same as when we ran it as a stand-alone container in [Part 2](part2.md) of the Quickstart tutorial.
4. Once satisfied, tear down your application:
```shell
kubectl delete -f bb.yaml
```
## Conclusion
At this point, we have successfully used Docker Desktop to deploy our application to a fully-featured Kubernetes environment on our development machine. We haven't done much with Kubernetes yet, but the door is now open; you can begin adding other components to your app and taking advantage of all the features and power of Kubernetes, right on your own machine.
In addition to deploying to Kubernetes, we have also described our application as a Kubernetes YAML file. This simple text file contains everything we need to create our application in a running state. We can check it into version control and share it with our colleagues, allowing us to distribute our applications to other clusters (like the testing and production clusters that probably come after our development environments) easily.
## Kubernetes references
Further documentation for all new Kubernetes objects used in this article are available here:
- [Kubernetes Pods](https://kubernetes.io/docs/concepts/workloads/pods/pod/)
- [Kubernetes Deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/)
- [Kubernetes Services](https://kubernetes.io/docs/concepts/services-networking/service/)

6
get-started/nav.html
View File

@ -1,7 +1,5 @@
<ul class="pagination">
<li {% if include.selected=="1"%}class="active"{% endif %}><a href="part1">Orientation and setup</a></li>
<li {% if include.selected=="2"%}class="active"{% endif %}><a href="part2">Containerizing an application</a></li>
<li {% if include.selected=="3"%}class="active"{% endif %}><a href="part3">Deploying to Kubernetes</a></li>
<li {% if include.selected=="4"%}class="active"{% endif %}><a href="part4">Deploying to Swarm</a></li>
<li {% if include.selected=="5"%}class="active"{% endif %}><a href="part5">Sharing images on Docker Hub</a></li>
<li {% if include.selected=="2"%}class="active"{% endif %}><a href="part2">Build and run your image</a></li>
<li {% if include.selected=="3"%}class="active"{% endif %}><a href="part3">Share images on Docker Hub</a></li>
</ul>

333
get-started/orchestration.md Normal file
View File

@ -0,0 +1,333 @@
---
title: "Orchestration"
keywords: orchestration, deploy, kubernetes, swarm,
description: Get oriented on some basics of Docker and install Docker Desktop.
---
The portability and reproducibility of a containerized process mean we have an opportunity to move and scale our containerized applications across clouds and datacenters. Containers effectively guarantee that those applications run the same way anywhere, allowing us to quickly and easily take advantage of all these environments. Furthermore, as we scale our applications up, we'll want some tooling to help automate the maintenance of those applications, able to replace failed containers automatically, and manage the rollout of updates and reconfigurations of those containers during their lifecycle.
Tools to manage, scale, and maintain containerized applications are called _orchestrators_, and the most common examples of these are _Kubernetes_ and _Docker Swarm_. Development environment deployments of both of these
orchestrators are provided by Docker Desktop, which we'll use throughout
this guide to create our first orchestrated, containerized application.
The advanced modules teach you how to:
1. [Set up and use a Kubernetes environment on your development machine](kube-deploy.md)
2. [Set up and use a Swarm environment on your development machine](swarm-deploy.md)
## Enable Kubernetes
Docker Desktop will set up Kubernetes for you quickly and easily. Follow the setup and validation instructions appropriate for your operating system:
<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" href="#kubeosx">Mac</a></li>
<li><a data-toggle="tab" href="#kubewin">Windows</a></li>
</ul>
<div class="tab-content">
<div id="kubeosx" class="tab-pane fade in active">
{% capture local-content %}
### Mac
1. After installing Docker Desktop, you should see a Docker icon in your menu bar. Click on it, and navigate to **Preferences** > **Kubernetes**.
2. Check the checkbox labeled **Enable Kubernetes**, and click **Apply & Restart**. Docker Desktop will automatically set up Kubernetes for you. You'll know that Kubernetes has been successfully enabled when you see a green light beside 'Kubernetes _running_' in the Preferences menu.
3. In order to confirm that Kubernetes is up and running, create a text file called `pod.yaml` with the following content:
```yaml
apiVersion: v1
kind: Pod
metadata:
name: demo
spec:
containers:
- name: testpod
image: alpine:3.5
command: ["ping", "8.8.8.8"]
```
This describes a pod with a single container, isolating a simple ping to 8.8.8.8.
4. In a terminal, navigate to where you created `pod.yaml` and create your pod:
```shell
kubectl apply -f pod.yaml
```
5. Check that your pod is up and running:
```shell
kubectl get pods
```
You should see something like:
```shell
NAME READY STATUS RESTARTS AGE
demo 1/1 Running 0 4s
```
6. Check that you get the logs you'd expect for a ping process:
```shell
kubectl logs demo
```
You should see the output of a healthy ping process:
```shell
PING 8.8.8.8 (8.8.8.8): 56 data bytes
64 bytes from 8.8.8.8: seq=0 ttl=37 time=21.393 ms
64 bytes from 8.8.8.8: seq=1 ttl=37 time=15.320 ms
64 bytes from 8.8.8.8: seq=2 ttl=37 time=11.111 ms
...
```
7. Finally, tear down your test pod:
```shell
kubectl delete -f pod.yaml
```
{% endcapture %}
{{ local-content | markdownify }}
</div>
<div id="kubewin" class="tab-pane fade" markdown="1">
{% capture localwin-content %}
### Windows
1. After installing Docker Desktop, you should see a Docker icon in your system tray. Right-click on it, and navigate **Settings** > **Kubernetes**.
2. Check the checkbox labeled **Enable Kubernetes**, and click **Apply & Restart**. Docker Desktop will automatically set up Kubernetes for you. You'll know that Kubernetes has been successfully enabled when you see a green light beside 'Kubernetes _running_' in the **Settings** menu.
3. In order to confirm that Kubernetes is up and running, create a text file called `pod.yaml` with the following content:
```yaml
apiVersion: v1
kind: Pod
metadata:
name: demo
spec:
containers:
- name: testpod
image: alpine:3.5
command: ["ping", "8.8.8.8"]
```
This describes a pod with a single container, isolating a simple ping to 8.8.8.8.
4. In PowerShell, navigate to where you created `pod.yaml` and create your pod:
```shell
kubectl apply -f pod.yaml
```
5. Check that your pod is up and running:
```shell
kubectl get pods
```
You should see something like:
```shell
NAME READY STATUS RESTARTS AGE
demo 1/1 Running 0 4s
```
6. Check that you get the logs you'd expect for a ping process:
```shell
kubectl logs demo
```
You should see the output of a healthy ping process:
```shell
PING 8.8.8.8 (8.8.8.8): 56 data bytes
64 bytes from 8.8.8.8: seq=0 ttl=37 time=21.393 ms
64 bytes from 8.8.8.8: seq=1 ttl=37 time=15.320 ms
64 bytes from 8.8.8.8: seq=2 ttl=37 time=11.111 ms
...
```
7. Finally, tear down your test pod:
```shell
kubectl delete -f pod.yaml
```
{% endcapture %}
{{ localwin-content | markdownify }}
</div>
<hr>
</div>
## Enable Docker Swarm
Docker Desktop runs primarily on Docker Engine, which has everything you need to run a Swarm built in. Follow the setup and validation instructions appropriate for your operating system:
<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" href="#swarmosx">Mac</a></li>
<li><a data-toggle="tab" href="#swarmwin">Windows</a></li>
</ul>
<div class="tab-content">
<div id="swarmosx" class="tab-pane fade in active">
{% capture local-content %}
### Mac
1. Open a terminal, and initialize Docker Swarm mode:
```shell
docker swarm init
```
If all goes well, you should see a message similar to the following:
```shell
Swarm initialized: current node (tjjggogqpnpj2phbfbz8jd5oq) is now a manager.
To add a worker to this swarm, run the following command:
docker swarm join --token SWMTKN-1-3e0hh0jd5t4yjg209f4g5qpowbsczfahv2dea9a1ay2l8787cf-2h4ly330d0j917ocvzw30j5x9 192.168.65.3:2377
To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions.
```
2. Run a simple Docker service that uses an alpine-based filesystem, and isolates a ping to 8.8.8.8:
```shell
docker service create --name demo alpine:3.5 ping 8.8.8.8
```
3. Check that your service created one running container:
```shell
docker service ps demo
```
You should see something like:
```shell
ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS
463j2s3y4b5o demo.1 alpine:3.5 docker-desktop Running Running 8 seconds ago
```
4. Check that you get the logs you'd expect for a ping process:
```shell
docker service logs demo
```
You should see the output of a healthy ping process:
```shell
demo.1.463j2s3y4b5o@docker-desktop | PING 8.8.8.8 (8.8.8.8): 56 data bytes
demo.1.463j2s3y4b5o@docker-desktop | 64 bytes from 8.8.8.8: seq=0 ttl=37 time=13.005 ms
demo.1.463j2s3y4b5o@docker-desktop | 64 bytes from 8.8.8.8: seq=1 ttl=37 time=13.847 ms
demo.1.463j2s3y4b5o@docker-desktop | 64 bytes from 8.8.8.8: seq=2 ttl=37 time=41.296 ms
...
```
5. Finally, tear down your test service:
```shell
docker service rm demo
```
{% endcapture %}
{{ local-content | markdownify }}
</div>
<div id="swarmwin" class="tab-pane fade" markdown="1">
{% capture localwin-content %}
### Windows
1. Open a powershell, and initialize Docker Swarm mode:
```shell
docker swarm init
```
If all goes well, you should see a message similar to the following:
```shell
Swarm initialized: current node (tjjggogqpnpj2phbfbz8jd5oq) is now a manager.
To add a worker to this swarm, run the following command:
docker swarm join --token SWMTKN-1-3e0hh0jd5t4yjg209f4g5qpowbsczfahv2dea9a1ay2l8787cf-2h4ly330d0j917ocvzw30j5x9 192.168.65.3:2377
To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions.
```
2. Run a simple Docker service that uses an alpine-based filesystem, and isolates a ping to 8.8.8.8:
```shell
docker service create --name demo alpine:3.5 ping 8.8.8.8
```
3. Check that your service created one running container:
```shell
docker service ps demo
```
You should see something like:
```shell
ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS
463j2s3y4b5o demo.1 alpine:3.5 docker-desktop Running Running 8 seconds ago
```
4. Check that you get the logs you'd expect for a ping process:
```shell
docker service logs demo
```
You should see the output of a healthy ping process:
```shell
demo.1.463j2s3y4b5o@docker-desktop | PING 8.8.8.8 (8.8.8.8): 56 data bytes
demo.1.463j2s3y4b5o@docker-desktop | 64 bytes from 8.8.8.8: seq=0 ttl=37 time=13.005 ms
demo.1.463j2s3y4b5o@docker-desktop | 64 bytes from 8.8.8.8: seq=1 ttl=37 time=13.847 ms
demo.1.463j2s3y4b5o@docker-desktop | 64 bytes from 8.8.8.8: seq=2 ttl=37 time=41.296 ms
...
```
5. Finally, tear down your test service:
```shell
docker service rm demo
```
{% endcapture %}
{{ localwin-content | markdownify }}
</div>
<hr>
</div>
## Conclusion
At this point, you've confirmed that you can run simple containerized workloads in Kubernetes and Swarm. The next step will be to write the Kubernetes yaml that describes how to run and manage these containers on Kubernetes.
[On to deploying to Kubernetes >>](kube-deploy.md){: class="button outline-btn" style="margin-bottom: 30px; margin-right: 200%"}
To learn how to write the stack file to help you run and manage containers on Swarm, see [Deploying to Swarm](swarm-deploy.md).
## CLI references
Further documentation for all CLI commands used in this article are available here:
- [`kubectl apply`](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#apply)
- [`kubectl get`](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#get)
- [`kubectl logs`](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#logs)
- [`kubectl delete`](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#delete)
- [`docker swarm init`](https://docs.docker.com/engine/reference/commandline/swarm_init/)
- [`docker service *`](https://docs.docker.com/engine/reference/commandline/service/)

167
get-started/part2.md
View File

@ -1,5 +1,5 @@
---
title: "Containerizing an application"
title: "Build and run your image"
keywords: containers, images, dockerfiles, node, code, coding, build, push, run
description: Learn how to create a Docker image by writing a Dockerfile, and use it to run a simple container.
---
@ -8,76 +8,149 @@ description: Learn how to create a Docker image by writing a Dockerfile, and use
## Prerequisites
- Work through setup and orientation in [Part 1](index.md).
Work through the orientation and setup in [Part 1](index.md).
## Introduction
Now that we've got our orchestrator of choice set up in our development environment thanks to Docker Desktop,
Now that we've set up our development environment, thanks to Docker Desktop,
we can begin to develop containerized applications. In general, the development workflow looks like this:
1. Create and test individual containers for each component of your application by first creating Docker images.
2. Assemble your containers and supporting infrastructure into a complete application, expressed either as a *Docker stack file* or in Kubernetes YAML.
3. Test, share and deploy your complete containerized application.
2. Assemble your containers and supporting infrastructure into a complete application.
3. Test, share, and deploy your complete containerized application.
In this stage of the tutorial, let's focus on step 1 of this workflow: creating the images that our containers will be based on. Remember, a Docker image captures the private filesystem that our containerized processes will run in; we need to create an image that contains just what our application needs to run.
> **Containerized development environments** are easier to set up than traditional development environments, once you learn how to build images as we'll discuss below. This is because a containerized development environment will isolate all the dependencies your app needs inside your Docker image; there's no need to install anything other than Docker on your development machine. In this way, you can easily develop applications for different stacks without changing anything on your development machine.
## Setting Up
## Set up
1. Clone an example project from GitHub (if you don't have git installed, see the [install instructions](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) first):
Let us download an example project from the [Docker Samples](https://github.com/dockersamples/node-bulletin-board) page.
```shell
git clone -b v1 https://github.com/docker-training/node-bulletin-board
cd node-bulletin-board/bulletin-board-app
```
<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" href="#clonegit">Git</a></li>
<li><a data-toggle="tab" href="#clonewin">Windows (without Git)</a></li>
<li><a data-toggle="tab" href="#clonemac">Mac or Linux (without Git)</a></li>
</ul>
<div class="tab-content">
<div id="clonegit" class="tab-pane fade in active">
{% capture git-clone-content %}
This is a simple bulletin board application, written in node.js. In this example, let's imagine you wrote this app, and are now trying to containerize it.
### Git
2. Have a look at the file called `Dockerfile`. Dockerfiles describe how to assemble a private filesystem for a container, and can also contain some metadata describing how to run a container based on this image. The bulletin board app Dockerfile looks like this:
If you are using Git, you can clone the example project from GitHub:
```dockerfile
FROM node:6.11.5
```shell
git clone https://github.com/dockersamples/node-bulletin-board
cd node-bulletin-board/bulletin-board-app
```
WORKDIR /usr/src/app
COPY package.json .
RUN npm install
COPY . .
{% endcapture %}
{{ git-clone-content | markdownify }}
CMD [ "npm", "start" ]
```
</div>
<div id="clonewin" class="tab-pane fade" markdown="1">
{% capture win-clone-content %}
Writing a Dockerfile is the first step to containerizing an application. You can think of these Dockerfile commands as a step-by-step recipe on how to build up our image. This one takes the following steps:
### Windows (without Git)
- Start `FROM` the pre-existing `node:6.11.5` image. This is an *official image*, built by the node.js vendors and validated by Docker to be a high-quality image containing the node 6.11.5 interpreter and basic dependencies.
- Use `WORKDIR` to specify that all subsequent actions should be taken from the directory `/usr/src/app` *in your image filesystem* (never the host's filesystem).
- `COPY` the file `package.json` from your host to the present location (`.`) in your image (so in this case, to `/usr/src/app/package.json`)
- `RUN` the command `npm install` inside your image filesystem (which will read `package.json` to determine your app's node dependencies, and install them)
- `COPY` in the rest of your app's source code from your host to your image filesystem.
If you are using a Windows machine and prefer to download the example project without installing Git, run the following commands in PowerShell:
You can see that these are much the same steps you might have taken to set up and install your app on your host - but capturing these as a Dockerfile allows us to do the same thing inside a portable, isolated Docker image.
```shell
curl.exe -LO https://github.com/dockersamples/node-bulletin-board/archive/master.zip
tar.exe xf master.zip
cd node-bulletin-board-master\bulletin-board-app
```
The steps above built up the filesystem of our image, but there's one more line in our Dockerfile. The `CMD` directive is our first example of specifying some metadata in our image that describes how to run a container based off of this image. In this case, it's saying that the containerized process that this image is meant to support is `npm start`.
{% endcapture %}
{{ win-clone-content | markdownify }}
</div>
What you see above is a good way to organize a simple Dockerfile; always start with a `FROM` command, follow it with the steps to build up your private filesystem, and conclude with any metadata specifications. There are many more Dockerfile directives than just the few we see above; for a complete list, see the [Dockerfile reference](https://docs.docker.com/engine/reference/builder/).
<div id="clonemac" class="tab-pane fade" markdown="1">
{% capture mac-clone-content %}
## Build and Test Your Image
### Mac or Linux (without Git)
If you are using a Mac or a Linux machine and prefer to download the example project without installing Git, run the following commands in a terminal:
```shell
curl -LO https://github.com/dockersamples/node-bulletin-board/archive/master.zip
unzip master.zip
cd node-bulletin-board-master/bulletin-board-app
```
{% endcapture %}
{{ mac-clone-content | markdownify }}
</div>
<hr>
</div>
The `node-bulletin-board` project is a simple bulletin board application, written in Node.js. In this example, let's imagine you wrote this app, and are now trying to containerize it.
## Define a container with Dockerfile
Take a look at the file called `Dockerfile` in the bulletin board application. Dockerfiles describe how to assemble a private filesystem for a container, and can also contain some metadata describing how to run a container based on this image. The bulletin board app Dockerfile looks like this:
```dockerfile
# Use the official image as a parent image
FROM node:current-slim
# Set the working directory
WORKDIR /usr/src/app
# Copy the file from your host to your current location
COPY package.json .
# Run the command inside your image filesystem
RUN npm install
# Inform Docker that the container is listening on the specified port at runtime.
EXPOSE 8080
# Run the specified command within the container.
CMD [ "npm", "start" ]
# Copy the rest of your app's source code from your host to your image filesystem.
COPY . .
```
Writing a Dockerfile is the first step to containerizing an application. You can think of these Dockerfile commands as a step-by-step recipe on how to build up our image. This one takes the following steps:
- Start `FROM` the pre-existing `node:current-slim` image. This is an *official image*, built by the node.js vendors and validated by Docker to be a high-quality image containing the Node.js Long Term Support (LTS) interpreter and basic dependencies.
- Use `WORKDIR` to specify that all subsequent actions should be taken from the directory `/usr/src/app` *in your image filesystem* (never the host's filesystem).
- `COPY` the file `package.json` from your host to the present location (`.`) in your image (so in this case, to `/usr/src/app/package.json`)
- `RUN` the command `npm install` inside your image filesystem (which will read `package.json` to determine your app's node dependencies, and install them)
- `COPY` in the rest of your app's source code from your host to your image filesystem.
You can see that these are much the same steps you might have taken to set up and install your app on your host. However, capturing these as a Dockerfile allows us to do the same thing inside a portable, isolated Docker image.
The steps above built up the filesystem of our image, but there are other lines in our Dockerfile.
The `CMD` directive is our first example of specifying some metadata in our image that describes how to run a container based on this image. In this case, it's saying that the containerized process that this image is meant to support is `npm start`.
The `EXPOSE 8080` informs Docker that the container is listening on port 8000 at runtime.
What you see above is a good way to organize a simple Dockerfile; always start with a `FROM` command, follow it with the steps to build up your private filesystem, and conclude with any metadata specifications. There are many more Dockerfile directives than just the few we see above; for a complete list, see the [Dockerfile reference](https://docs.docker.com/engine/reference/builder/).
## Build and test your image
Now that we have some source code and a Dockerfile, it's time to build our first image, and make sure the containers launched from it work as expected.
> **Windows users**: this example uses Linux containers. Make sure your environment is running Linux containers by right-clicking on the Docker logo in your system tray, and clicking 'Switch to Linux containers...' if the option appears. Don't worry - everything you'll learn in this tutorial works the exact same way for Windows containers.
> **Windows users**: this example uses Linux containers. Make sure your environment is running Linux containers by right-clicking on the Docker logo in your system tray, and clicking **Switch to Linux containers** if the option appears. Don't worry - all the commands in this tutorial work the exact same way for Windows containers.
1. Make sure you're in the directory `node-bulletin-board/bulletin-board-app` in a terminal or powershell, and build your bulletin board image:
Make sure you're in the directory `node-bulletin-board/bulletin-board-app` in a terminal or PowerShell using the `cd` command. Let's build your bulletin board image:
```script
docker image build -t bulletinboard:1.0 .
```
```script
docker image build -t bulletinboard:1.0 .
```
You'll see Docker step through each instruction in your Dockerfile, building up your image as it goes. If successful, the build process should end with a message `Successfully tagged bulletinboard:1.0`.
You'll see Docker step through each instruction in your Dockerfile, building up your image as it goes. If successful, the build process should end with a message `Successfully tagged bulletinboard:1.0`.
> **Windows Users:** you may receive a message titled 'SECURITY WARNING' at this step, noting the read, write and execute permissions being set for files added to your image; we aren't handling any sensitive information in this example, so feel free to disregard this warning in this example.
> **Windows users:** you may receive a message titled 'SECURITY WARNING' at this step, noting the read, write, and execute permissions being set for files added to your image. We aren't handling any sensitive information in this example, so feel free to disregard the warning in this example.
2. Start a container based on your new image:
## Run your image as a container
1. Start a container based on your new image:
```script
docker container run --publish 8000:8080 --detach --name bb bulletinboard:1.0
@ -91,24 +164,26 @@ Now that we have some source code and a Dockerfile, it's time to build our first
Also notice, we didn't specify what process we wanted our container to run. We didn't have to, since we used the `CMD` directive when building our Dockerfile; thanks to this, Docker knows to automatically run the process `npm start` inside our container when it starts up.
3. Visit your application in a browser at `localhost:8000`. You should see your bulletin board application up and running. At this step, we would normally do everything we could to ensure our container works the way we expected; now would be the time to run unit tests, for example.
2. Visit your application in a browser at `localhost:8000`. You should see your bulletin board application up and running. At this step, we would normally do everything we could to ensure our container works the way we expected; now would be the time to run unit tests, for example.
4. Once you're satisfied that your bulletin board container works correctly, delete it:
3. Once you're satisfied that your bulletin board container works correctly, you can delete it:
```script
docker container rm --force bb
```
The `--force` option removes the running container.
## Conclusion
At this point, we've performed a simple containerization of an application, and confirmed that our app runs successfully in its container. The next step will be to write the Kubernetes yaml that describes how to run and manage these containers on Kubernetes which we'll study in Part 3 of this tutorial, or to write the stack file that will let us do the same on Docker Swarm, which we discuss in Part 4.
At this point, we've successfully built an image, performed a simple containerization of an application, and confirmed that our app runs successfully in its container. The next step will be to share your images on [Docker Hub](https://hub.docker.com/), so they can be easily downloaded and run on any destination machine.
[On to Part 3 >>](part3.md){: class="button outline-btn" style="margin-bottom: 30px; margin-right: 100%"}
## CLI References
## CLI references
Further documentation for all CLI commands used in this article are available here:
- [docker image *](https://docs.docker.com/engine/reference/commandline/image/)
- [docker container *](https://docs.docker.com/engine/reference/commandline/container/)
- [Dockerfile reference](https://docs.docker.com/engine/reference/builder/)
- [docker image](https://docs.docker.com/engine/reference/commandline/image/)
- [docker container](https://docs.docker.com/engine/reference/commandline/container/)
- [Dockerfile reference](https://docs.docker.com/engine/reference/builder/)

138
get-started/part3.md
View File

@ -1,135 +1,69 @@
---
title: "Deploying to Kubernetes"
keywords: kubernetes, pods, deployments, kubernetes services
description: Learn how to describe and deploy a simple application on Kubernetes.
title: "Share images on Docker Hub"
keywords: docker hub, push, images
description: Learn how to share images on Docker Hub.
redirect_from:
- /get-started/part5/
---
{% include_relative nav.html selected="3" %}
## Prerequisites
- Work through containerizing an application in [Part 2](part2.md).
- Make sure that Kubernetes is enabled on your Docker Desktop:
- **OSX**: click the Docker icon in your menu bar and make sure there's a green light beside 'Kubernetes is Running'
- **Windows**: click the Docker icon in the system tray and navigate to Kubernetes, and make sure there's a green light beside 'Kubernetes is Running'.
If Kubernetes isn't running, follow the instructions in [Part 1](part1.md) of this tutorial to finish setting it up.
Work through the steps to build an image and run it as a containerized application in [Part 2](part2.md).
## Introduction
Now that we've demonstrated that the individual components of our application run as stand-alone containers, it's time to arrange for them to be managed by an orchestrator like Kubernetes. Kubernetes provides many tools for scaling, networking, securing and maintaining your containerized applications, above and beyond the abilities of containers themselves.
At this point, you've built a containerized application in [Part 2](part2.md) on your local development machine, thanks to Docker Desktop. The final step in developing a containerized application is to share your images on a registry like [Docker Hub](https://hub.docker.com/), so they can be easily downloaded and run on any destination machine.
In order to validate that our containerized application works well on Kubernetes, we'll use Docker Desktop's built in Kubernetes environment right on our development machine to deploy our application, before handing it off to run on a full Kubernetes cluster in production. The Kubernetes environment created by Docker Desktop is _fully featured_, meaning it has all the Kubernetes features your app will enjoy on a real cluster, accessible from the convenience of your development machine.
## Set up your Docker Hub account
## Describing Apps Using Kubernetes YAML
If you don't yet have a Docker ID, follow these steps to set one up; this will allow you to share images on Docker Hub.
All containers in Kubernetes are scheduled as _pods_, which are groups of co-located containers that share some resources. Furthermore, in a realistic application we almost never create individual pods; instead, most of our workloads are scheduled as _deployments_, which are scalable groups of pods maintained automatically by Kubernetes. Lastly, all Kubernetes objects can and should be described in manifests called _Kubernetes YAML_ files; these YAML files describe all the components and configurations of your Kubernetes app, and can be used to easily create and destroy your app in any Kubernetes environment.
1. Visit the Docker Hub sign up page, [https://hub.docker.com/signup](https://hub.docker.com/signup).
1. You already wrote a very basic Kubernetes YAML file in the first part of this tutorial; let's write a slightly more sophisticated one now, to run and manage our bulletin board. Place the following in a file called `bb.yaml`:
2. Fill out the form and submit to create your Docker ID.
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: bb-demo
namespace: default
spec:
replicas: 1
selector:
matchLabels:
bb: web
template:
metadata:
labels:
bb: web
spec:
containers:
- name: bb-site
image: bulletinboard:1.0
---
apiVersion: v1
kind: Service
metadata:
name: bb-entrypoint
namespace: default
spec:
type: NodePort
selector:
bb: web
ports:
- port: 8080
targetPort: 8080
nodePort: 30001
```
3. Verify your email address to complete the registration process.
In this Kubernetes YAML file, we have two objects, separated by the `---`:
- A `Deployment`, describing a scalable group of identical pods. In this case, you'll get just one `replica`, or copy, of your pod, and that pod (which is described under the `template:` key) has just one container in it, based off of your `bulletinboard:1.0` image from the previous step in this tutorial.
- A `NodePort` service, which will route traffic from port 30001 on your host to port 8080 inside the pods it routes to, allowing you to reach your bulletin board from the network.
4. Click on the Docker icon in your toolbar or system tray, and click **Sign in / Create Docker ID**.
Also notice that while Kubernetes YAML can appear long and complicated at first, it almost always follows the same pattern:
- The `apiVersion`, which indicates the Kubernetes API that parses this object
- The `kind`, indicating what sort of object this is
- Some `metadata`, applying things like names to your objects
- The `spec`, specifying all the parameters and configurations of your object.
5. Fill in your new Docker ID and password. After you have successfully authenticated, your Docker ID appears in the Docker Desktop menu in place of the 'Sign in' option you just used.
## Deploying and Checking Your Application
> You can do the same thing from the command line by typing `docker login`.
1. In a terminal, navigate to where you created `bb.yaml` and deploy your application to Kubernetes:
## Create a Docker Hub repository and push your image
At this point, you've set up your Docker Hub account and have connected it to your Docker Desktop. Now let's make our first repo, and share our bulletin board app there.
1. Click on the Docker icon in your menu bar, and navigate to **Repositories > Create**. You'll be taken to a Docker Hub page to create a new repository.
2. Fill out the repository name as `bulletinboard`. Leave all the other options alone for now, and click **Create** at the bottom.
![make a repo](images/newrepo.png){:width="100%"}
3. Now we're ready to share our image on Docker Hub, but there's one thing we must do first: images must be *namespaced correctly* to share on Docker Hub. Specifically, images must be named like `<Docker ID>/<Repository Name>:<tag>`. We can relabel our `bulletinboard:1.0` image like this (of course, please replace `gordon` with your Docker ID):
```shell
kubectl apply -f bb.yaml
docker image tag bulletinboard:1.0 gordon/bulletinboard:1.0
```
you should see output that looks like the following, indicating your Kubernetes objects were created successfully:
4. Finally, push your image to Docker Hub:
```shell
deployment.apps/bb-demo created
service/bb-entrypoint created
docker image push gordon/bulletinboard:1.0
```
2. Make sure everything worked by listing your deployments:
Visit your repository in Docker Hub, and you'll see your new image there. Remember, Docker Hub repositories are public by default.
```shell
kubectl get deployments
```
if all is well, your deployment should be listed as follows:
```shell
NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE
bb-demo 1 1 1 1 48s
```
This indicates all one of the pods you asked for in your YAML are up and running. Do the same check for your services:
```shell
kubectl get services
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
bb-entrypoint NodePort 10.106.145.116 <none> 8080:30001/TCP 53s
kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 138d
```
In addition to the default `kubernetes` service, we see our `bb-entrypoint` service, accepting traffic on port 30001/TCP.
3. Open a browser and visit your bulletin board at `localhost:30001`; you should see your bulletin board, the same as when we ran it as a stand-alone container in the previous step of this tutorial.
4. Once satisfied, tear down your application:
```shell
kubectl delete -f bb.yaml
```
> **Having trouble pushing?** Remember, you must be signed in to Docker Hub through Docker Desktop or the command line, and you must also name your images correctly, as per the above steps. If the push seemed to work, but you don't see it in Docker Hub, refresh your browser after a couple of minutes and check again.
## Conclusion
At this point, we have successfully used Docker Desktop to deploy our application to a fully-featured Kubernetes environment on our development machine. We haven't done much with Kubernetes yet, but the door is now open: you can begin adding other components to your app and taking advantage of all the features and power of Kubernetes, right on your own machine.
Now that your image is available on Docker Hub, you'll be able to run it anywhere. If you try to use it on a new machine that doesn't have it yet, Docker will automatically try and download it from Docker Hub. By moving images around in this way, you no longer need to install any dependencies except Docker on the machines you want to run our software on. The dependencies of containerized applications are completely encapsulated and isolated within your images, which we can share using Docker Hub as described above.
In addition to deploying to Kubernetes, we have also described our application as a Kubernetes YAML file. This simple text file contains everything we need to create our application in a running state; we can check it into version control and share it with our colleagues, allowing us to distribute our applications to other clusters (like the testing and production clusters that probably come after our development environments) easily.
Another thing to keep in mind: at the moment, we've only pushed your image to Docker Hub; what about your Dockerfile? A crucial best practice is to keep these in version control, perhaps alongside your source code for your application. You can add a link or note in your Docker Hub repository description indicating where these files can be found, preserving the record not only of how your image was built, but how it's meant to be run as a full application.
## Kubernetes References
Further documentation for all new Kubernetes objects used in this article are available here:
- [Kubernetes Pods](https://kubernetes.io/docs/concepts/workloads/pods/pod/)
- [Kubernetes Deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/)
- [Kubernetes Services](https://kubernetes.io/docs/concepts/services-networking/service/)
## Where to go next
We recommend that you take a look at the topics in [Develop with Docker](/develop/index.md) to learn how to develop your own applications using Docker.

59
get-started/part5.md
View File

@ -1,59 +0,0 @@
---
title: "Sharing images on Docker Hub"
keywords: docker hub, push, images
description: Learn how to share images on Docker Hub.
---
{% include_relative nav.html selected="5" %}
## Prerequisites
- Work through containerizing an application in [Part 2](part2.md).
## Introduction
At this point, you've built a containerized application in [Part 2](part2.md), and potentially run it on Kubernetes in [Part 3](part3.md) or Swarm in [Part 4](part4.md), all on your local development machine thanks to Docker Desktop. The final step in developing a containerized application is to share your images on a registry like [Docker Hub](https://hub.docker.com/), so they can be easily downloaded and run on any destination cluster.
## Setting Up Your Docker Hub Account
If you don't yet have a Docker ID, follow these steps to set one up; this will allow you to share images on Docker Hub.
1. Visit the Docker Hub sign up page, [https://hub.docker.com/signup](https://hub.docker.com/signup).
2. Fill out the form and submit to create your Docker ID.
3. Click on the Docker icon in your toolbar or system tray, and click **Sign In / Create Docker ID**. Fill in your new Docker ID and password. If everything worked, your Docker ID will appear in the Docker Desktop dropdown in place of the 'Sign In' option you just used.
> You can do the same thing from the command line by typing `docker login`.
## Creating and Pushing to a Docker Hub Repository
At this point, you've set up your Docker Hub account and have connected it to your Docker Desktop. Now let's make our first repo, and share our bulletin board app there.
1. Click on the Docker icon in your menu bar, and navigate to **Repositories -> Create...**. You'll be taken to a Docker Hub page to create a new repository.
2. Fill out the Repository Name as `bulletinboard`. Leave all the other options alone for now, and click **Create** at the bottom.
![make a repo](images/newrepo.png){:width="100%"}
3. Now we're ready to share our image on Docker Hub, but there's one thing we must do first: images must be *namespaced correctly* to share on Docker Hub. Specifically, images must be named like `<Docker Hub ID>/<Repository Name>:<tag>`. We can relabel our `bulletinboard:1.0` image like this (of course please replace `gordon` with your Docker ID):
```shell
docker image tag bulletinboard:1.0 gordon/bulletinboard:1.0
```
4. Finally, push your image to Docker Hub:
```shell
docker image push gordon/bulletinboard:1.0
```
Visit your repository in Docker Hub, and you'll see your new image there. Remember, Docker Hub repositories are public by default.
> **Having trouble pushing?** Remember, you must be signed in to Docker Hub through Docker Desktop or the command line, and you must also name your images correctly, per the above steps. If the push seemed to work but you don't see it in Docker Hub, refresh your browser after a couple of minutes and check again.
## Conclusion
Now that your image is available on Docker Hub, you'll be able to run it anywhere; if you try to use it on a new cluster that doesn't have it yet, Docker will automatically try and download it from Docker Hub. By moving images around in this way, we no longer need to install any dependencies except Docker and our orchestrator on the machines we want to run our software on; the dependencies of our containerized applications are completely encapsulated and isolated within our images, which we can share via Docker Hub in the manner above.
Another thing to keep in mind: at the moment, we've only pushed your image to Docker Hub; what about your Dockerfiles, Kube YAML and stack files? A crucial best practice is to keep these in version control, perhaps alongside your source code for your application, and add a link or note in your Docker Hub repository description indicating where these files can be found, preserving the record not only of how your image was built, but how it's meant to be run as a full application.

32
get-started/part4.md → get-started/swarm-deploy.md
View File

@ -1,16 +1,18 @@
---
title: "Deploying to Swarm"
title: "Deploy to Swarm"
keywords: swarm, swarm services, stacks
description: Learn how to describe and deploy a simple application on Docker Swarm.
redirect_from:
- /get-started/part4/
---
{% include_relative nav.html selected="4" %}
## Prerequisites
- Download and install Docker Desktop as described in [Orientation and setup](/index.md).
- Work through containerizing an application in [Part 2](part2.md).
- Make sure that Swarm is enabled on your Docker Desktop by typing `docker system info`, and looking for a message `Swarm: active` (you might have to scroll up a little).
If Swarm isn't running, simply type `docker swarm init` at a shell prompt to set it up.
If Swarm isn't running, simply type `docker swarm init` in a shell prompt to set it up.
## Introduction
@ -18,28 +20,27 @@ Now that we've demonstrated that the individual components of our application ru
In order to validate that our containerized application works well on Swarm, we'll use Docker Desktop's built in Swarm environment right on our development machine to deploy our application, before handing it off to run on a full Swarm cluster in production. The Swarm environment created by Docker Desktop is _fully featured_, meaning it has all the Swarm features your app will enjoy on a real cluster, accessible from the convenience of your development machine.
## Describing Apps Using Stack Files
## Describe apps using stack files
Swarm never creates individual containers like we did in the previous step of this tutorial; instead, all Swarm workloads are scheduled as _services_, which are scalable groups of containers with added networking features maintained automatically by Swarm. Furthermore, all Swarm objects can and should be described in manifests called _stack files_; these YAML files describe all the components and configurations of your Swarm app, and can be used to easily create and destroy your app in any Swarm environment.
Swarm never creates individual containers like we did in the previous step of this tutorial. Instead, all Swarm workloads are scheduled as _services_, which are scalable groups of containers with added networking features maintained automatically by Swarm. Furthermore, all Swarm objects can and should be described in manifests called _stack files_. These YAML files describe all the components and configurations of your Swarm app, and can be used to easily create and destroy your app in any Swarm environment.
1. Let's write a simple stack file to run and manage our bulletin board. Place the following in a file called `bb-stack.yaml`:
Let's write a simple stack file to run and manage our bulletin board. Place the following in a file called `bb-stack.yaml`:
```yaml
version: '3.7'
version: '3.7'
services:
bb-app:
image: bulletinboard:1.0
ports:
- "8000:8080"
- "8000:8080"
```
In this Swarm YAML file, we have just one object: a `service`, describing a scalable group of identical containers. In this case, you'll get just one container (the default), and that container will be based off of your `bulletinboard:1.0` image from step 2 of this tutorial. We've furthermore asked Swarm to forward all traffic arriving at port 8000 on our development machine to port 8080 inside our bulletin board container.
In this Swarm YAML file, we have just one object: a `service`, describing a scalable group of identical containers. In this case, you'll get just one container (the default), and that container will be based off of your `bulletinboard:1.0` image created in [Part 2](part2.md) of the Quickstart tutorial. In addition, We've asked Swarm to forward all traffic arriving at port 8000 on our development machine to port 8080 inside our bulletin board container.
> **Kubernetes Services and Swarm Services are very different!** Despite the similar name, the two orchestrators mean very different things by the term 'service'. In Swarm, a service provides both scheduling _and_ networking facilities, creating containers and providing tools for routing traffic to them. In Kubernetes, scheduling and networking are handled separately: _deployments_ (or other controllers) handle the scheduling of containers as pods, while _services_ are responsible only for adding networking features to those pods.
## Deploying and Checking Your Application
## Deploy and check your application
1. Deploy your application to Swarm:
@ -71,7 +72,7 @@ Swarm never creates individual containers like we did in the previous step of th
This indicates 1/1 containers you asked for as part of your services are up and running. Also, we see that port 8000 on your development machine is getting forwarded to port 8080 in your bulletin board container.
3. Open a browser and visit your bulletin board at `localhost:8000`; you should see your bulletin board, the same as when we ran it as a stand-alone container in Step 2 of this tutorial.
3. Open a browser and visit your bulletin board at `localhost:8000`; you should see your bulletin board, the same as when we ran it as a stand-alone container in Part 2 of the Quickstart tutorial.
4. Once satisfied, tear down your application:
@ -85,9 +86,7 @@ At this point, we have successfully used Docker Desktop to deploy our applicatio
In addition to deploying to Swarm, we have also described our application as a stack file. This simple text file contains everything we need to create our application in a running state; we can check it into version control and share it with our colleagues, allowing us to distribute our applications to other clusters (like the testing and production clusters that probably come after our development environments) easily.
[On to Part 5 >>](part5.md){: class="button outline-btn" style="margin-bottom: 30px; margin-right: 100%"}
## Swarm &amp; CLI References
## Swarm and CLI references
Further documentation for all new Swarm objects and CLI commands used in this article are available here:
@ -95,4 +94,3 @@ Further documentation for all new Swarm objects and CLI commands used in this ar
- [Swarm Stacks](https://docs.docker.com/engine/swarm/stack-deploy/)
- [`docker stack *`](https://docs.docker.com/engine/reference/commandline/stack/)
- [`docker service *`](https://docs.docker.com/engine/reference/commandline/service/)