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

Merge branch 'chrisward/further-scout-tweaks' into chrisward/scout-tweaks

This commit is contained in:
Chris Chinchilla 2023-03-07 15:03:32 +01:00
parent 1cc5a83729 45dc503304
commit c7a683f45d
4 changed files with 113 additions and 103 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
_config.yml
View File

@ -153,8 +153,7 @@ defaults:
fetch-remote:
- repo: "https://github.com/docker/cli"
default_branch: "master"
# FIXME(thaJeztah): change to 23.0 release branch, once created.
ref: "master"
ref: "23.0"
paths:
- dest: "engine/extend"
src:
@ -172,12 +171,7 @@ fetch-remote:
- repo: "https://github.com/docker/docker"
default_branch: "master"
# The default branch has separate files for each API version, so we can
# consume the swagger files from that branch (we only publish the ones
# that have been released through the stubs in the engine/api/ directory).
# Using the default (master) branch allows for API docs changes to be
# published without them being cherry-picked into the release branch.
ref: "master"
ref: "23.0"
paths:
- dest: "engine/api"
src:

4
docker-hub/onboard-team.md
View File

@ -11,7 +11,7 @@ The following section contains step-by-step instructions on how to get started o
## Prerequisites
Before you start to on board your organization, ensure that you've completed the following:
- You have a Docker Team subscription. You can verify your subscription in Docker Hub's [Billing Details](https://hub.docker.com/billing){: target="_blank" rel="noopener" class="_"}. If you haven't subscribed to Team Business yet, see [Upgrade your subscription](../subscription/upgrade.md) for details about upgrading.
- You have a Docker Team subscription. You can verify your subscription in Docker Hub's [Billing Details](https://hub.docker.com/billing){: target="_blank" rel="noopener" class="_"}. If you haven't subscribed to Docker Team yet, see [Upgrade your subscription](../subscription/upgrade.md) for details about upgrading.
- You are familiar with Docker terminology. If you discover any unfamiliar terms, see the [glossary](/glossary/#docker) or [FAQs](../docker-hub/onboarding-faqs.md).
## Step 1: Identify your Docker users and their Docker accounts
@ -31,7 +31,7 @@ To begin, you should identify which users you will need to add to your Docker Te
## Step 2: Invite owners
Now that you have a Docker Team organization, it's time to start adding owners to help you set up and manage your organization. Owners can add or remove members, and configure Single Sign-on as well as other security settings.
Now that you have a Docker Team organization, it's time to start adding owners to help you set up and manage your organization. Owners can add or remove members, and configure other organization settings.
To add an owner, invite a user to the **owners** team. For more details, see [Invite members](../docker-hub/members.md/#invite-members){: target="_blank" rel="noopener" class="_"}.

132
get-started/07_multi_container.md
View File

@ -1,22 +1,20 @@
---
title: "Multi container apps"
keywords: get started, setup, orientation, quickstart, intro, concepts, containers, docker desktop
description: Using more than one container in our application
description: Using more than one container in your application
---
Up to this point, we have been working with single container apps. But, we now want to add MySQL to the
Up to this point, you've been working with single container apps. But, now you will add MySQL to the
application stack. The following question often arises - "Where will MySQL run? Install it in the same
container or run it separately?" In general, **each container should do one thing and do it well.** A few
reasons:
container or run it separately?" In general, each container should do one thing and do it well. The following are a few reasons to run the container separately:
- There's a good chance you'd have to scale APIs and front-ends differently than databases.
- Separate containers let you version and update versions in isolation.
- While you may use a container for the database locally, you may want to use a managed service
for the database in production. You don't want to ship your database engine with your app then.
- Running multiple processes will require a process manager (the container only starts one process),
which adds complexity to container startup/shutdown.
- Running multiple processes will require a process manager (the container only starts one process), which adds complexity to container startup/shutdown.
And there are more reasons. So, we will update our application to work like this:
And there are more reasons. So, like the following diagram, it's best to run your app in multiple containers.
![Todo App connected to MySQL container](images/multi-app-architecture.png)
{: .text-center }
@ -24,30 +22,34 @@ And there are more reasons. So, we will update our application to work like this
## Container networking
Remember that containers, by default, run in isolation and don't know anything about other processes
or containers on the same machine. So, how do we allow one container to talk to another? The answer is
**networking**. Now, you don't have to be a network engineer (hooray!). Simply remember this rule...
> **Note**
>
> If two containers are on the same network, they can talk to each other. If they aren't, they can't.
or containers on the same machine. So, how do you allow one container to talk to another? The answer is
networking. If you place the two containers on the same network, they can talk to each other.
## Start MySQL
There are two ways to put a container on a network:
1) Assign it at start or
2) connect an existing container.
For now, we will create the network first and attach the MySQL container at startup.
- Assign the network when starting the container.
- Connect an already running container to a network.
In the following steps, you'll create the network first and then attach the MySQL container at startup.
1. Create the network.
```console
$ docker network create todo-app
```
```console
$ docker network create todo-app
```
2. Start a MySQL container and attach it to the network. We're also going to define a few environment variables that the
database will use to initialize the database (see the "Environment Variables" section in the [MySQL Docker Hub listing](https://hub.docker.com/_/mysql/)).
2. Start a MySQL container and attach it to the network. You're also going to define a few environment variables that the
database will use to initialize the database. To learn more about the MySQL environment variables, see the "Environment Variables" section in the [MySQL Docker Hub listing](https://hub.docker.com/_/mysql/)).
```console
<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" data-target="#mac-linux">Mac / Linux</a></li>
<li><a data-toggle="tab" data-target="#windows">Windows</a></li>
</ul>
<div class="tab-content">
<div id="mac-linux" class="tab-pane fade in active" markdown="1">
```console
$ docker run -d \
--network todo-app --network-alias mysql \
-v todo-mysql-data:/var/lib/mysql \
@ -56,7 +58,11 @@ For now, we will create the network first and attach the MySQL container at star
mysql:8.0
```
If you are using Windows then use this command in PowerShell.
<hr>
</div>
<div id="windows" class="tab-pane fade" markdown="1">
In Windows, run this command in PowerShell.
```powershell
$ docker run -d `
@ -67,19 +73,23 @@ For now, we will create the network first and attach the MySQL container at star
mysql:8.0
```
You'll also see we specified the `--network-alias` flag. We'll come back to that in just a moment.
<hr>
</div>
</div>
In the command above, you'll see the `--network-alias` flag. In a later section, you'll learn more about this flag.
> **Tip**
>
> You'll notice we're using a volume named `todo-mysql-data` here and mounting it at `/var/lib/mysql`, which is where MySQL stores its data. However, we never ran a `docker volume create` command. Docker recognizes we want to use a named volume and creates one automatically for us.
> You'll notice a volume named `todo-mysql-data` in the above command that is mounted at `/var/lib/mysql`, which is where MySQL stores its data. However, you never ran a `docker volume create` command. Docker recognizes you want to use a named volume and creates one automatically for you.
3. To confirm we have the database up and running, connect to the database and verify it connects.
3. To confirm you have the database up and running, connect to the database and verify that it connects.
```console
$ docker exec -it <mysql-container-id> mysql -u root -p
```
When the password prompt comes up, type in **secret**. In the MySQL shell, list the databases and verify
When the password prompt comes up, type in `secret`. In the MySQL shell, list the databases and verify
you see the `todos` database.
```console
@ -100,22 +110,22 @@ For now, we will create the network first and attach the MySQL container at star
+--------------------+
5 rows in set (0.00 sec)
```
Exit the MySQL shell to return to the shell on our machine.
4. Exit the MySQL shell to return to the shell on your machine.
```console
mysql> exit
```
Hooray! We have our `todos` database and it's ready for us to use!
You now have a `todos` database and it's ready for you to use.
## Connect to MySQL
Now that we know MySQL is up and running, let's use it! But, the question is... how? If we run
another container on the same network, how do we find the container (remember each container has its own IP
address)?
Now that you know MySQL is up and running, you can use it. But, how do you use it? If you run
another container on the same network, how do you find the container? Remember that each container has its own IP address.
To figure it out, we're going to make use of the [nicolaka/netshoot](https://github.com/nicolaka/netshoot) container,
which ships with a _lot_ of tools that are useful for troubleshooting or debugging networking issues.
To answer the questions above and better understand container networking, you're going to make use of the [nicolaka/netshoot](https://github.com/nicolaka/netshoot) container,
which ships with a lot of tools that are useful for troubleshooting or debugging networking issues.
1. Start a new container using the nicolaka/netshoot image. Make sure to connect it to the same network.
@ -123,14 +133,14 @@ which ships with a _lot_ of tools that are useful for troubleshooting or debuggi
$ docker run -it --network todo-app nicolaka/netshoot
```
2. Inside the container, we're going to use the `dig` command, which is a useful DNS tool. We're going to look up
2. Inside the container, you're going to use the `dig` command, which is a useful DNS tool. You're going to look up
the IP address for the hostname `mysql`.
```console
$ dig mysql
```
And you'll get an output like this...
You should get output like the following.
```text
; <<>> DiG 9.18.8 <<>> mysql
@ -153,11 +163,11 @@ which ships with a _lot_ of tools that are useful for troubleshooting or debuggi
In the "ANSWER SECTION", you will see an `A` record for `mysql` that resolves to `172.23.0.2`
(your IP address will most likely have a different value). While `mysql` isn't normally a valid hostname,
Docker was able to resolve it to the IP address of the container that had that network alias (remember the
`--network-alias` flag we used earlier?).
Docker was able to resolve it to the IP address of the container that had that network alias. Remember, you used the
`--network-alias` earlier.
What this means is... our app only simply needs to connect to a host named `mysql` and it'll talk to the
database! It doesn't get much simpler than that!
What this means is that your app only simply needs to connect to a host named `mysql` and it'll talk to the
database.
## Run your app with MySQL
@ -168,9 +178,9 @@ The todo app supports the setting of a few environment variables to specify MySQ
- `MYSQL_PASSWORD` - the password to use for the connection
- `MYSQL_DB` - the database to use once connected
> **Setting Connection Settings via Env Vars**
> **Note**
>
> While using env vars to set connection settings is generally ok for development, it is **HIGHLY DISCOURAGED**
> While using env vars to set connection settings is generally accepted for development, it's highly discouraged
> when running applications in production. Diogo Monica, a former lead of security at Docker,
> [wrote a fantastic blog post](https://diogomonica.com/2017/03/27/why-you-shouldnt-use-env-variables-for-secret-data/){:target="_blank" rel="noopener" class="_"}
> explaining why.
@ -183,14 +193,16 @@ The todo app supports the setting of a few environment variables to specify MySQ
> as the connection password. Docker doesn't do anything to support these env vars. Your app will need to know to look for
> the variable and get the file contents.
With all of that explained, let's start our dev-ready container!
You can now start your dev-ready container.
1. **Note**: for MySQL versions 8.0 and higher, make sure to include the following commands in `mysql`.
```console
mysql> ALTER USER 'root' IDENTIFIED WITH mysql_native_password BY 'secret';
mysql> flush privileges;
```
2. We'll specify each of the environment variables above, as well as connect the container to our app network.
1. Specify each of the environment variables above, as well as connect the container to your app network.
<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" data-target="#mac-linux2">Mac / Linux</a></li>
<li><a data-toggle="tab" data-target="#windows2">Windows</a></li>
</ul>
<div class="tab-content">
<div id="mac-linux2" class="tab-pane fade in active" markdown="1">
```console
$ docker run -dp 3000:3000 \
@ -204,7 +216,11 @@ With all of that explained, let's start our dev-ready container!
sh -c "yarn install && yarn run dev"
```
If you are using Windows then use this command in PowerShell.
<hr>
</div>
<div id="windows2" class="tab-pane fade" markdown="1">
In Windows, run this command in PowerShell.
```powershell
$ docker run -dp 3000:3000 `
@ -217,7 +233,11 @@ With all of that explained, let's start our dev-ready container!
node:18-alpine `
sh -c "yarn install && yarn run dev"
```
3. If we look at the logs for the container (`docker logs -f <container-id>`), we should see a message indicating it's
<hr>
</div>
</div>
2. If you look at the logs for the container (`docker logs -f <container-id>`), you should see a message similar to the following, which indicates it's
using the mysql database.
```console
@ -230,10 +250,10 @@ With all of that explained, let's start our dev-ready container!
Listening on port 3000
```
4. Open the app in your browser and add a few items to your todo list.
3. Open the app in your browser and add a few items to your todo list.
5. Connect to the mysql database and prove that the items are being written to the database. Remember, the password
is **secret**.
4. Connect to the mysql database and prove that the items are being written to the database. Remember, the password
is `secret`.
```console
$ docker exec -it <mysql-container-id> mysql -p todos
@ -251,7 +271,7 @@ With all of that explained, let's start our dev-ready container!
+--------------------------------------+--------------------+-----------+
```
Obviously, your table will look different because it has your items. But, you should see them stored there!
Your table will look different because it has your items. But, you should see them stored there.
## Next steps
@ -263,6 +283,6 @@ this application. You have to create a network, start containers, specify all of
ports, and more! That's a lot to remember and it's certainly making things harder to pass along to someone else.
In the next section, you'll learn about Docker Compose. With Docker Compose, you can share your application stacks in a
much easier way and let others spin them up with a single (and simple) command!
much easier way and let others spin them up with a single, simple command.
[Use Docker Compose](08_using_compose.md){: .button .primary-btn}

70
scout/image-details-view.md
View File

@ -11,8 +11,8 @@ description: >
> product, and requires a Pro, Team, or Business subscription.
The image details view shows a breakdown of the Docker Scout analysis. You can
access the image view both from within Docker Desktop, and from the image tag
page on Docker Hub. This view provides a breakdown of the image hierarchy (base
access the image view from within Docker Desktop and from the image tag
page on Docker Hub. The view provides a breakdown of the image hierarchy (base
images), image layers, packages, and vulnerabilities.
The image view lets you inspect the composition of an image from different
@ -22,16 +22,15 @@ or for a specific base image or layer.
![The image details view in Docker Desktop](./images/dd-image-view.png){:width="700px"}
## Image Hierarchy
## Image hierarchy
The image you inspect may have one or more base images listed under **Image hierarchy**.
This means the author of the image used another image as a starting
point when building the image. Often these base images are either operating
The image you inspect may have one or more base images represented under **Image hierarchy**.
This means the author of the image used other images as starting
points when building the image. Often these base images are either operating
system images such as Debian, Ubuntu, and Alpine, or programming language images
such as PHP, Python, and Java.
A base image may have its own parent base image so there is a chain of base
images represented in **Image hierarchy**. Selecting each image in the chain
Selecting each image in the chain
lets you see which layers originate from each base image. Selecting the **ALL**
row reselects all the layers and base images for the entire image.
@ -44,22 +43,20 @@ images with available updates are noted to the right of **Image hierarchy**.
A Docker image consists of layers. Image layers are listed from top to bottom,
with the earliest layer at the top and the most recent layer at the bottom.
Often, the layers at the top of the list originate from a base image, and the
layers towards the bottom are layers added by the image author, often by adding
commands to a Dockerfile. To see which layers originate from a base image,
simply select a base image under **Image hierarchy** and the relevant layers are
highlighted.
layers towards the bottom added by the image author, often using
commands in a Dockerfile. Selecting a base image under **Image hierarchy**
highlights with layers originate from a base image.
Selecting individual or multiple layers filters the packages and vulnerabilities
on the right-hand side to see what has been added by the selected layers.
on the right-hand side to show what the selected layers added.
## Vulnerabilities
Images may be exposed to vulnerabilities and exploits. These are detected and
listed on the right-hand side, grouped by package, and sorted in order of
severity. Further information on whether the vulnerability has an available fix,
for example, can be examined by expanding the sections.
The **Vulnerabilities** tab displays a list of vulnerabilities and exploits detected in the image. The list is grouped by package, and sorted in order of severity.
## Remediation
You can find further information on the vulnerability or exploit, including if a fix is available, by expanding the list item.
## Remediation recommendations
In Docker Hub and Docker Desktop 4.17 and later versions, when inspecting an
image, you can get recommended actions for improving the security of that image.
@ -80,8 +77,8 @@ the current image or any base images used to build it:
- [**Recommendations for base image**](#recommendations-for-base-image) provides
recommendations for base images used to build the image.
If the image you're viewing has no associated base images, only the option to
view recommendations for the current image displays here.
If the image you're viewing has no associated base images, the dropdown only
shows the option to view recommendations for the current image.
### Recommendations in Docker Hub
@ -104,12 +101,12 @@ To view security recommendations for an image in Docker Hub:
>
> This recommendation is only available in Docker Desktop.
Recommendations for the current image helps you determine whether the image
version that you're using is out of date. If tag you're using is referencing an
old digest, you'll receive a recommendation to update your tag by pulling the
latest version of the tag.
The recommendations for the current image view helps you determine whether the image
version that you're using is out of date. If the tag you're using is referencing an
old digest, the view shows a recommendation to update the tag by pulling the
latest version.
Select the **Pull new image** button to get the updated version. Select the
Select the **Pull new image** button to get the updated version. Check the
checkbox to remove the old version after pulling the latest.
### Recommendations for base image
@ -117,16 +114,16 @@ checkbox to remove the old version after pulling the latest.
The base image recommendations view contains two tabs for toggling between
different types of recommendations:
- Refresh base image
- Change base image
- **Refresh base image**
- **Change base image**
These base image recommendations are only actionable if you're the author of the
image you're inspecting. That's because changing the base image for an image
image you're inspecting. This is because changing the base image for an image
requires you to update the Dockerfile and re-build the image.
#### Refresh base image
This tab shows you if you if the selected base image tag is the latest available
This tab shows if the selected base image tag is the latest available
version, or if it's outdated.
If the base image tag used to build the current image isn't the latest, then the
@ -138,23 +135,22 @@ includes:
- The age of the latest available version
- The number of CVEs affecting each version
At the bottom of the window, you also receive command snippets that you can run
to re-build the image using the latest version.
At the bottom of the window, you also receive command snippets that you can
run to re-build the image using the latest version.
#### Change base image
This tab can present you with different alternative tags that you can use, and
outlines the benefits and disadvantages of each tag version. Select base image
tag, and receive recommended options for that tag.
This tab shows different alternative tags that you can use, and
outlines the benefits and disadvantages of each tag version. Selecting the base image shows recommended options for that tag.
For example, if the image you're inspecting is using an old version of `debian`
as a base image, you can get recommendations for newer and more secure versions
as a base image, it shows recommendations for newer and more secure versions
of `debian` to use. By providing more than one alternative to choose from, you
can see for yourself how the options compare with each other, and decide which
one to use.
![Base image recommendations](./images/change-base-image.png){:width="700px"}
Select a tag recommendation to receive further details of the recommendation.
You'll see the benefits and potential disadvantages of this tag, why it's a
Select a tag recommendation to see further details of the recommendation.
It shows the benefits and potential disadvantages of the tag, why it's a
recommended, and how to update your Dockerfile to use this version.