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

[ENGDOCS-1012] Get started refresh part 1 & 2 (#15965) 

* get started refresh part 1 and 2
This commit is contained in:
Craig Osterhout 2022-10-27 15:32:47 -07:00 committed by GitHub
parent 1bf018d4a4
commit da7b60072d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
10 changed files with 105 additions and 186 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
_data/toc.yaml
View File

@ -29,7 +29,7 @@ guides:
path: /get-docker/
- sectiontitle: Get started
section:
- title: "Part 1: Orientation and setup"
- title: "Part 1: Overview"
path: /get-started/
- title: "Part 2: Containerize an application"
path: /get-started/02_our_app/

123
get-started/02_our_app.md
View File

@ -6,39 +6,37 @@ redirect_from:
description: Containerize and run a simple application to learn Docker
---
For the rest of this guide, you will be working with a simple todo
list manager that's running in Node.js. If you're not familiar with Node.js,
don't worry. This guide doesn't require JavaScript experience.
For the rest of this tutorial, we will be working with a simple todo
list manager that is running in Node.js. If you're not familiar with Node.js,
don't worry. No real JavaScript experience is needed.
To complete this guide, you'll need the following:
At this point, your development team is quite small and you're simply
building an app to prove out your MVP (minimum viable product). You want
to show how it works and what it's capable of doing without needing to
think about how it will work for a large team, multiple developers, etc.
![Todo List Manager Screenshot](images/todo-list-sample.png){: style="width:50%;" }
- Docker running locally. Follow the instructions to [download and install Docker](../get-docker.md).
- A [Git client](https://git-scm.com/downloads){:target="_blank" rel="noopener" class="_"}.
- An IDE or a text editor to edit files. Docker recommends using [Visual Studio Code](https://code.visualstudio.com/){:target="_blank" rel="noopener" class="_"}.
- A conceptual understanding of [containers and images](../get-started/overview.md/#docker-objects).
## Get the app
Before we can run the application, we need to get the application source code onto
our machine. For real projects, you will typically clone the repo. But, for this tutorial,
we have created a ZIP file containing the application.
Before you can run the application, you need to get the application source code onto your machine.
1. Download the App contents from the [getting-started repository](https://github.com/docker/getting-started/tree/master){:target="_blank" rel="noopener" class="_"}. You can either pull the entire project or [download it as a zip](https://github.com/docker/getting-started/archive/refs/heads/master.zip) and extract the app folder out to get started with.
1. Clone the [getting-started repository](https://github.com/docker/getting-started/tree/master){:target="_blank" rel="noopener" class="_"} using the following command:
2. Once extracted, use your favorite code editor to open the project. If you're in need of
an editor, you can use [Visual Studio Code](https://code.visualstudio.com/){:target="_blank" rel="noopener" class="_"}. You should
see the `package.json` and two subdirectories (`src` and `spec`).
```console
$ git clone https://github.com/docker/getting-started.git
```
2. View the contents of the cloned repository. Inside the `getting-started/app` directory you should see `package.json` and two subdirectories (`src` and `spec`).
![Screenshot of Visual Studio Code opened with the app loaded](images/ide-screenshot.png){: style="width:650px;margin-top:20px;"}
{: .text-center }
## Build the app's container image
In order to build the application, you'll need to use a `Dockerfile`. A
Dockerfile is simply a text-based file with no file extension. A Dockerfile contains a script of instructions that are used to create a container image.
In order to build the [container image](../get-started/overview.md/#docker-objects){:target="_blank" rel="noopener" class="_"}, you'll need to use a `Dockerfile`. A Dockerfile is simply a text-based file with no file extension. A Dockerfile contains a script of instructions that Docker uses to create a container image.
1. In the `app` folder, the same location as the `package.json` file, create a file named `Dockerfile`. You can use the following commands below to create a Dockerfile based on your operating system.
1. In the `app` directory, the same location as the `package.json` file, create a file named `Dockerfile`. You can use the following commands below to create a Dockerfile based on your operating system.
<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" data-target="#mac-linux">Mac / Linux</a></li>
@ -49,26 +47,34 @@ Dockerfile is simply a text-based file with no file extension. A Dockerfile cont
In the terminal, run the following commands listed below.
```console
$ cd /path/to/app
$ touch Dockerfile
```
Change directory to the `app` directory. Replace `/path/to/app` with the path to your `getting-started/app` directory.
```console
$ cd /path/to/app
```
Create an empty file named `Dockerfile`.
```console
$ touch Dockerfile
```
<hr>
<hr>
</div>
<div id="windows" class="tab-pane fade" markdown="1">
In the Windows Command Prompt, run the following commands listed below.
In the Windows Command Prompt, run the following commands listed below.
```console
$ cd \path\to\app
$ type nul > Dockerfile
```
Change directory to the `app` directory. Replace `\path\to\app` with the path to your `getting-started\app` directory.
```console
$ cd \path\to\app
```
Create an empty file named `Dockerfile`.
```console
$ type nul > Dockerfile
```
<hr>
</div>
</div>
2. Add the following contents to the Dockerfile. If you've created Dockerfiles before, you might see a few flaws in the Dockerfile below. But, don't worry. We'll go over them.
2. Using a text editor or code editor, add the following contents to the Dockerfile:
```dockerfile
# syntax=docker/dockerfile:1
@ -80,72 +86,63 @@ Dockerfile is simply a text-based file with no file extension. A Dockerfile cont
CMD ["node", "src/index.js"]
EXPOSE 3000
```
> **Note**
>
> Select an instruction in the Dockerfile example to learn more about the instruction.
> **Note**
>
> Select an instruction in the Dockerfile example to learn more about the instruction.
3. Open a terminal and go to the `app` directory with the `Dockerfile`. Now build the container image using the `docker build` command.
3. Build the container image using the following commands:
In the terminal, change directory to the `getting-started/app` directory. Replace `/path/to/app` with the path to your `getting-started/app` directory.
```console
$ cd /path/to/app
```
Build the container image.
```console
$ docker build -t getting-started .
```
This command used the Dockerfile to build a new container image. You might
have noticed that a lot of "layers" were downloaded. This is because we instructed
the builder that we wanted to start from the `node:12-alpine` image. But, since we
didn't have that on our machine, that image needed to be downloaded.
The `docker build` command uses the Dockerfile to build a new container image. You might have noticed that Docker downloaded a lot of "layers". This is because you instructed the builder that you wanted to start from the `node:12-alpine` image. But, since you didn't have that on your machine, Docker needed to download the image.
After the image was downloaded, we copied in our application and used `yarn` to
install our application's dependencies. The `CMD` directive specifies the default
command to run when starting a container from this image.
After Docker downloaded the image, the instructions from the Dockerfile copied in your application and used `yarn` to install your application's dependencies. The `CMD` directive specifies the default command to run when starting a container from this image.
Finally, the `-t` flag tags our image. Think of this simply as a human-readable name
for the final image. Since we named the image `getting-started`, we can refer to that
image when we run a container.
Finally, the `-t` flag tags your image. Think of this simply as a human-readable name for the final image. Since you named the image `getting-started`, you can refer to that image when you run a container.
The `.` at the end of the `docker build` command tells Docker that it should look for the `Dockerfile` in the current directory.
## Start an app container
Now that we have an image, let's run the application. To do so, we will use the `docker run`
command (remember that from earlier?).
Now that you have an image, you can run the application in a [container](../get-started/overview.md/#docker-objects){:target="_blank" rel="noopener" class="_"}. To do so, you will use the `docker run` command.
1. Start your container using the `docker run` command and specify the name of the image we
just created:
1. Start your container using the `docker run` command and specify the name of the image you just created:
```console
$ docker run -dp 3000:3000 getting-started
```
Remember the `-d` and `-p` flags? We're running the new container in "detached" mode (in the
background) and creating a mapping between the host's port 3000 to the container's port 3000.
Without the port mapping, we wouldn't be able to access the application.
You use the `-d` flag to run the new container in "detached" mode (in the background). You also use the `-p` flag to create a mapping between the host's port 3000 to the container's port 3000.
Without the port mapping, you wouldn't be able to access the application.
2. After a few seconds, open your web browser to [http://localhost:3000](http://localhost:3000).
You should see our app.
2. After a few seconds, open your web browser to [http://localhost:3000](http://localhost:3000){:target="_blank" rel="noopener" class="_"}.
You should see your app.
![Empty Todo List](images/todo-list-empty.png){: style="width:450px;margin-top:20px;"}
{: .text-center }
3. Go ahead and add an item or two and see that it works as you expect. You can mark items as
complete and remove items. Your frontend is successfully storing items in the backend.
Pretty quick and easy, huh?
3. Go ahead and add an item or two and see that it works as you expect. You can mark items as complete and remove items. Your frontend is successfully storing items in the backend.
At this point, you should have a running todo list manager with a few items, all built by you.
Now, let's make a few changes and learn about managing our containers.
If you take a quick look at the Docker Dashboard, you should see your two containers running now
(this tutorial and your freshly launched app container).
If you take a quick look at your Docker Dashboard, you should see at least one container running that is using the `getting-started` image and on port `3000`.
![Docker Dashboard with tutorial and app containers running](images/dashboard-two-containers.png)
## Next steps
In this short section, you learned the basics about building a container image and created a
Dockerfile to do so. Once you built an image, you started the container and saw the running app.
In this short section, you learned the basics about creating a Dockerfile to build a container image. Once you built an image, you started a container and saw the running app.
Next, you're going to make a modification to your app and learn how to update your running application
with a new image. Along the way, you'll learn a few other useful commands.
Next, you're going to make a modification to your app and learn how to update your running application with a new image. Along the way, you'll learn a few other useful commands.
[Update the application](03_updating_app.md){: .button .primary-btn}

24
get-started/11_what_next.md
View File

@ -28,3 +28,27 @@ solve problems around monitoring, logging, security, image registries, messaging
So, if you're new to the container landscape and cloud-native application development, welcome! Please
connect with the community, ask questions, and keep learning! We're excited to have you!
## Getting started video workshop
We recommend the video workshop from DockerCon 2022. Watch the video below or use the links to open the video at a particular section.
* [Docker overview and installation](https://youtu.be/gAGEar5HQoU)
* [Pull, run, and explore containers](https://youtu.be/gAGEar5HQoU?t=1400)
* [Build a container image](https://youtu.be/gAGEar5HQoU?t=3185)
* [Containerize an app](https://youtu.be/gAGEar5HQoU?t=4683)
* [Connect a DB and set up a bind mount](https://youtu.be/gAGEar5HQoU?t=6305)
* [Deploy a container to the cloud](https://youtu.be/gAGEar5HQoU?t=8280)
<iframe src="https://www.youtube-nocookie.com/embed/gAGEar5HQoU" style="max-width: 100%; aspect-ratio: 16 / 9;" width="560" height="auto" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
## Creating a container from scratch
If you'd like to see how containers are built from scratch, Liz Rice from Aqua Security has a fantastic talk in which she creates a container from scratch in Go. While the talk does not go into networking, using images for the filesystem, and other advanced topics, it gives a deep dive into how things are working.
<iframe src="https://www.youtube-nocookie.com/embed/8fi7uSYlOdc" style="max-width: 100%; aspect-ratio: 16 / 9;" width="560" height="auto" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
## Language-specific guides
If you are looking for information on how to containerize an application using your favorite language, see [Language-specific getting started guides](../language/index.md).

125
get-started/index.md
View File

@ -1,7 +1,7 @@
---
title: "Orientation and setup"
keywords: get started, setup, orientation, quickstart, intro, concepts, containers, docker desktop
description: Get oriented on some basics of Docker and install Docker Desktop.
title: "Overview"
keywords: get started, overview, quickstart, intro, concepts, containers, images
description: Get an overview of the Get started guide and learn about containers and images.
redirect_from:
- /engine/getstarted-voting-app/
- /engine/getstarted-voting-app/cleanup/
@ -57,139 +57,40 @@ redirect_from:
- /windows/step_two/
---
> **Update to the Docker Desktop terms**
>
> Commercial use of Docker Desktop in larger enterprises (more than 250
> employees OR more than $10 million USD in annual revenue) now requires a paid
> subscription.
{: .important}
Welcome! We're excited that you want to learn Docker.
Welcome! We are excited that you want to learn Docker.
This page contains step-by-step instructions on how to get started with Docker. In this tutorial, you'll learn how to:
This guide contains step-by-step instructions on how to get started with Docker. Some of the things you'll learn and do in this guide are:
- Build and run an image as a container
- Share images using Docker Hub
- Deploy Docker applications using multiple containers with a database
- Run applications using Docker Compose
In addition, you'll also learn about the best practices for building images, including instructions on how to scan your images for security vulnerabilities.
If you are looking for information on how to containerize an application using your favorite language, see [Language-specific getting started guides](../language/index.md).
We also recommend the video workshop from DockerCon 2022. Watch the video below or use the links to open the video at a particular section.
* [Docker overview and installation](https://youtu.be/gAGEar5HQoU)
* [Pull, run, and explore containers](https://youtu.be/gAGEar5HQoU?t=1400)
* [Build a container image](https://youtu.be/gAGEar5HQoU?t=3185)
* [Containerize an app](https://youtu.be/gAGEar5HQoU?t=4683)
* [Connect a DB and set up a bind mount](https://youtu.be/gAGEar5HQoU?t=6305)
* [Deploy a container to the cloud](https://youtu.be/gAGEar5HQoU?t=8280)
<iframe src="https://www.youtube-nocookie.com/embed/gAGEar5HQoU" style="max-width: 100%; aspect-ratio: 16 / 9;" width="560" height="auto" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
## Download and install Docker
This tutorial assumes you have a current version of Docker installed on your
machine. If you do not have Docker installed, choose your preferred operating system below to download Docker:
[Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/Docker.dmg?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-mac-amd64){: .button .primary-btn }
[Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/Docker.dmg?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-mac-arm64){: .button .primary-btn }
[Windows](https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-win-amd64){: .button .primary-btn }
[Linux](../desktop/install/linux-install.md){: .button .primary-btn}
For Docker Desktop installation instructions, see:
- [Install Docker Desktop on Mac](../desktop/install/mac-install.md)
- [Install Docker Desktop on Windows](../desktop/install/windows-install.md)
- [Install Docker Desktop on Linux](../desktop/install/linux-install.md)
## Start the tutorial
If you've already run the command to get started with the tutorial, congratulations! If not, open a command prompt or bash window, and run the command:
```console
$ docker run -d -p 80:80 docker/getting-started
```
You'll notice a few flags being used. Here's some more info on them:
- `-d` - Run the container in detached mode (in the background).
- `-p 80:80` - Map port 80 of the host to port 80 in the container. To access the tutorial, open a web browser and navigate to `http://localhost:80`. If you already have a service listening on port 80 on your host machine, you can specify another port. For example, specify `-p 3000:80` and then access the tutorial via a web browser at `http://localhost:3000`.
- `docker/getting-started` - Specify the image to use.
> **Tip**
>
> You can combine single character flags to shorten the full command.
> As an example, the command above could be written as:
>
> ```console
> $ docker run -dp 80:80 docker/getting-started
> ```
## The Docker Dashboard
Before going too far, we want to highlight the Docker Dashboard, which gives
you a quick view of the containers running on your machine. The Docker Dashboard is available for Mac, Windows, and Linux.
It gives you quick access to container logs, lets you get a shell inside the container, and lets you
easily manage container lifecycles (stop, remove, etc.).
To access the dashboard, follow the instructions in the
[Docker Desktop manual](../desktop/index.md). If you open the dashboard
now, you will see this tutorial running! The container name (`jolly_bouman` below) is a
randomly created name. So, you'll most likely have a different name.
![Tutorial container running in Docker Dashboard](images/tutorial-in-dashboard.png)
Before you get to the hands on part of the guide, you should learn about containers and images.
## What is a container?
Now that you've run a container, what _is_ a container? Simply put, a container is
a sandboxed process on your machine that is isolated from all other processes
on the host machine. That isolation leverages [kernel namespaces and cgroups](https://medium.com/@saschagrunert/demystifying-containers-part-i-kernel-space-2c53d6979504),
features that have been in Linux for a long time. Docker has worked to make these
capabilities approachable and easy to use. To summarize, a container:
Simply put, a container is a sandboxed process on your machine that is isolated from all other processes on the host machine. That isolation leverages [kernel namespaces and cgroups](https://medium.com/@saschagrunert/demystifying-containers-part-i-kernel-space-2c53d6979504),
features that have been in Linux for a long time. Docker has worked to make these capabilities approachable and easy to use. To summarize, a container:
- is a runnable instance of an image. You can create, start, stop, move, or delete a container using the DockerAPI or CLI.
- can be run on local machines, virtual machines or deployed to the cloud.
- is portable (can be run on any OS).
- is isolated from other containers and runs its own software, binaries, and configurations.
> **Creating containers from scratch**
>
> If you'd like to see how containers are built from scratch, Liz Rice from Aqua Security
> has a fantastic talk in which she creates a container from scratch in Go. While the talk
> does not go into networking, using images for the filesystem, and other advanced topics,
> it gives a _fantastic_ deep dive into how things are working.
>
> <iframe src="https://www.youtube-nocookie.com/embed/8fi7uSYlOdc" style="max-width: 100%; aspect-ratio: 16 / 9;" width="560" height="auto" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
## What is a container image?
When running a container, it uses an isolated filesystem. This custom filesystem is provided
by a **container image**. Since the image contains the container's filesystem, it must contain everything
needed to run an application - all dependencies, configurations, scripts, binaries, etc. The
image also contains other configuration for the container, such as environment variables,
a default command to run, and other metadata.
When running a container, it uses an isolated filesystem. This custom filesystem is provided by a container image. Since the image contains the container's filesystem, it must contain everything needed to run an application - all dependencies, configurations, scripts, binaries, etc. The image also contains other configuration for the container, such as environment variables, a default command to run, and other metadata.
We'll dive deeper into images later on, covering topics such as layering, best practices, and more.
You'll dive deeper into images later on in this guide, covering topics such as layering, best practices, and more.
> **Info**
> **Note**
>
> If you're familiar with `chroot`, think of a container as an extended version of `chroot`. The
> filesystem is simply coming from the image. But, a container adds additional isolation not
> available when simply using chroot.
## CLI references
Refer to the following topics for further documentation on all CLI commands used in this article:
- [docker version](../engine/reference/commandline/version.md)
- [docker run](../engine/reference/commandline/run.md)
- [docker image](../engine/reference/commandline/image.md)
- [docker container](../engine/reference/commandline/container.md)
> If you're familiar with `chroot`, think of a container as an extended version of `chroot`. The filesystem is simply coming from the image. But, a container adds additional isolation not available when simply using chroot.
## Next steps
In this section, you installed Docker, learned about Docker, and learned about containers and images.
In this section, you learned about containers and images.
In the next section, you'll containerize your first application.

2
get-started/kube-deploy.md
View File

@ -6,7 +6,7 @@ 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).
- Download and install Docker Desktop as described in [Get Docker](../get-docker.md).
- Work through containerizing an application in [Part 2](02_our_app.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'.

2
get-started/swarm-deploy.md
View File

@ -8,7 +8,7 @@ redirect_from:
## Prerequisites
- Download and install Docker Desktop as described in [Orientation and setup](index.md).
- Download and install Docker Desktop as described in [Get Docker](../get-docker.md).
- Work through containerizing an application in [Part 2](02_our_app.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).

4
language/golang/build-images.md
View File

@ -13,12 +13,12 @@ redirect_from:
* Some understanding of Go and its toolchain. This is not a tutorial on Go. If
you are new to the language, the [Go website](https://golang.org/){: target="_blank" rel="noopener" class="_"}
is a good starting point, so go (pun intended) check it out.
* You understand basic Docker concepts, and you have completed the orientation
and setup in Get started [Part 1](../../get-started/index.md).
* You understand basic [Docker concepts](../../get-started/overview.md).
* You're familiar with the [Dockerfile format](../../build/building/packaging.md#dockerfile).
* You have [enabled BuildKit](../../build/buildkit/index.md#getting-started)
on your machine.
## Overview
Now that we have a good overview of containers and the Docker platform, let’s

3
language/java/build-images.md
View File

@ -8,8 +8,7 @@ description: Learn how to build your first Docker image by writing a Dockerfile
## Prerequisites
* You understand basic Docker concepts, and you have completed the orientation
and setup in Get started [Part 1](../../get-started/index.md).
* You understand basic [Docker concepts](../../get-started/overview.md).
* You're familiar with the [Dockerfile format](../../build/building/packaging.md#dockerfile).
* You have [enabled BuildKit](../../build/buildkit/index.md#getting-started)
on your machine.

3
language/nodejs/build-images.md
View File

@ -10,8 +10,7 @@ redirect_from:
## Prerequisites
* You understand basic Docker concepts, and you have completed the orientation
and setup in Get started [Part 1](../../get-started/index.md).
* You understand basic [Docker concepts](../../get-started/overview.md).
* You're familiar with the [Dockerfile format](../../build/building/packaging.md#dockerfile).
* You have [enabled BuildKit](../../build/buildkit/index.md#getting-started)
on your machine.

3
language/python/build-images.md
View File

@ -8,8 +8,7 @@ description: Learn how to build your first Docker image by writing a Dockerfile
## Prerequisites
* You understand basic Docker concepts, and you have completed the orientation
and setup in Get started [Part 1](../../get-started/index.md).
* You understand basic [Docker concepts](../../get-started/overview.md).
* You're familiar with the [Dockerfile format](../../build/building/packaging.md#dockerfile).
* You have [enabled BuildKit](../../build/buildkit/index.md#getting-started)
on your machine.