Merge 5b7e3ad95b into 2ef123150d

docs/tutorial/image-building-best-practices/index.md

@@ -1,3 +1,46 @@
+## Security Scanning
+
+When you have built an image, it is good practice to scan it for security vulnerabilities using the `docker scan` command.
+Docker has partnered with [Snyk](http://snyk.io) to provide the vulnerability scanning service.
+
+For example, to scan the `getting-started` image you created earlier in the tutorial, you can just type
+
+```bash
+docker scan getting-started
+```
+
+The scan uses a constantly updated database of vulnerabilities, so the output you see will vary as new
+vulnerabilities are discovered, but it might look something like this:
+
+```plaintext
+✗ Low severity vulnerability found in freetype/freetype
+  Description: CVE-2020-15999
+  Info: https://snyk.io/vuln/SNYK-ALPINE310-FREETYPE-1019641
+  Introduced through: freetype/freetype@2.10.0-r0, gd/libgd@2.2.5-r2
+  From: freetype/freetype@2.10.0-r0
+  From: gd/libgd@2.2.5-r2 > freetype/freetype@2.10.0-r0
+  Fixed in: 2.10.0-r1
+
+✗ Medium severity vulnerability found in libxml2/libxml2
+  Description: Out-of-bounds Read
+  Info: https://snyk.io/vuln/SNYK-ALPINE310-LIBXML2-674791
+  Introduced through: libxml2/libxml2@2.9.9-r3, libxslt/libxslt@1.1.33-r3, nginx-module-xslt/nginx-module-xslt@1.17.9-r1
+  From: libxml2/libxml2@2.9.9-r3
+  From: libxslt/libxslt@1.1.33-r3 > libxml2/libxml2@2.9.9-r3
+  From: nginx-module-xslt/nginx-module-xslt@1.17.9-r1 > libxml2/libxml2@2.9.9-r3
+  Fixed in: 2.9.9-r4
+```
+
+The output lists the type of vulnerability, a URL to learn more, and importantly which version of the relevant library
+fixes the vulnerability.
+
+There are several other options, which you can read about in the [docker scan documentation](https://docs.docker.com/engine/scan/).
+
+As well as scanning your newly built image on the command line, you can also [configure Docker Hub](https://docs.docker.com/docker-hub/vulnerability-scanning/)
+to scan all newly pushed images automatically, and you can then see the results in both Docker Hub and Docker Desktop.
+
+![Hub vulnerability scanning](hvs.png){: style=width:75% }
+{: .text-center }
 
 ## Image Layering
 
@@ -222,6 +265,6 @@ into an nginx container. Cool, huh?
 ## Recap
 
 By understanding a little bit about how images are structured, we can build images faster and ship fewer changes.
+Scanning images gives us confidence that the containers we are running and distributing are secure.
 Multi-stage builds also help us reduce overall image size and increase final container security by separating
 build-time dependencies from runtime dependencies.
-

docs/tutorial/multi-container-apps/index.md

@@ -37,8 +37,8 @@ For now, we will create the network first and attach the MySQL container at star
     docker network create todo-app
     ```
 
-1. Start a MySQL container and attach it 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/)) (replace the ` \ ` characters with `` ` `` in Windows PowerShell).
+1. 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/)).
 
     ```bash
     docker run -d \
@@ -49,6 +49,17 @@ For now, we will create the network first and attach the MySQL container at star
         mysql:5.7
     ```
 
+    If you are using PowerShell then use this command.
+
+    ```powershell
+    docker run -d `
+        --network todo-app --network-alias mysql `
+        -v todo-mysql-data:/var/lib/mysql `
+        -e MYSQL_ROOT_PASSWORD=secret `
+        -e MYSQL_DATABASE=todos `
+        mysql:5.7
+    ```
+
     You'll also see we specified the `--network-alias` flag. We'll come back to that in just a moment.
 
     !!! info "Pro-tip"
@@ -156,7 +167,7 @@ The todo app supports the setting of a few environment variables to specify MySQ
     
     A more secure mechanism is to use the secret support provided by your container orchestration framework. In most cases,
     these secrets are mounted as files in the running container. You'll see many apps (including the MySQL image and the todo app)
-    also support env vars with a `_FILE` suffix to point to a file containing the file. 
+    also support env vars with a `_FILE` suffix to point to a file containing the variable. 
     
     As an example, setting the `MYSQL_PASSWORD_FILE` var will cause the app to use the contents of the referenced file 
     as the connection password. Docker doesn't do anything to support these env vars. Your app will need to know to look for
@@ -165,11 +176,11 @@ The todo app supports the setting of a few environment variables to specify MySQ
 
 With all of that explained, let's start our dev-ready container!
 
-1. We'll specify each of the environment variables above, as well as connect the container to our app network (replace the ` \ ` characters with `` ` `` in Windows PowerShell).
+1. We'll specify each of the environment variables above, as well as connect the container to our app network.
 
     ```bash hl_lines="3 4 5 6 7"
     docker run -dp 3000:3000 \
-      -w /app -v ${PWD}:/app \
+      -w /app -v "$(pwd):/app" \
       --network todo-app \
       -e MYSQL_HOST=mysql \
       -e MYSQL_USER=root \
@@ -179,6 +190,20 @@ With all of that explained, let's start our dev-ready container!
       sh -c "yarn install && yarn run dev"
     ```
 
+    If you are using PowerShell then use this command.
+
+    ```powershell hl_lines="3 4 5 6 7"
+    docker run -dp 3000:3000 `
+      -w /app -v "$(pwd):/app" `
+      --network todo-app `
+      -e MYSQL_HOST=mysql `
+      -e MYSQL_USER=root `
+      -e MYSQL_PASSWORD=secret `
+      -e MYSQL_DB=todos `
+      node:12-alpine `
+      sh -c "yarn install && yarn run dev"
+    ```
+
 1. If we look at the logs for the container (`docker logs <container-id>`), we should see a message indicating it's
    using the mysql database.
 
@@ -199,7 +224,7 @@ With all of that explained, let's start our dev-ready container!
    is **secret**.
 
     ```bash
-    docker exec -ti <mysql-container-id> mysql -p todos
+    docker exec -it <mysql-container-id> mysql -p todos
     ```
 
     And in the mysql shell, run the following:

docs/tutorial/our-application/index.md

@@ -38,6 +38,7 @@ see a few flaws in the Dockerfile below. But, don't worry! We'll go over them.
 
     ```dockerfile
     FROM node:12-alpine
+    RUN apk add --no-cache python g++ make
     WORKDIR /app
     COPY . .
     RUN yarn install --production

docs/tutorial/using-bind-mounts/index.md

@@ -14,7 +14,7 @@ changes and then restart the application. There are equivalent tools in most oth
 ## Quick Volume Type Comparisons
 
 Bind mounts and named volumes are the two main types of volumes that come with the Docker engine. However, additional
-volume drivers are available to support other uses cases ([SFTP](https://github.com/vieux/docker-volume-sshfs), [Ceph](https://ceph.com/geen-categorie/getting-started-with-the-docker-rbd-volume-plugin/), [NetApp](https://netappdvp.readthedocs.io/en/stable/), [S3](https://github.com/elementar/docker-s3-volume), and more).
+volume drivers are available to support other use cases ([SFTP](https://github.com/vieux/docker-volume-sshfs), [Ceph](https://ceph.com/geen-categorie/getting-started-with-the-docker-rbd-volume-plugin/), [NetApp](https://netappdvp.readthedocs.io/en/stable/), [S3](https://github.com/elementar/docker-s3-volume), and more).
 
 |   | Named Volumes | Bind Mounts |
 | - | ------------- | ----------- |
@@ -36,18 +36,27 @@ So, let's do it!
 
 1. Make sure you don't have any previous `getting-started` containers running.
 
-1. Run the following command (replace the ` \ ` characters with `` ` `` in Windows PowerShell). We'll explain what's going on afterwards:
+1. Run the following command. We'll explain what's going on afterwards:
 
     ```bash
     docker run -dp 3000:3000 \
-        -w /app -v ${PWD}:/app \
+        -w /app -v "$(pwd):/app" \
         node:12-alpine \
         sh -c "yarn install && yarn run dev"
     ```
 
+    If you are using PowerShell then use this command.
+
+    ```powershell
+    docker run -dp 3000:3000 `
+        -w /app -v "$(pwd):/app" `
+        node:12-alpine `
+        sh -c "yarn install && yarn run dev"
+    ```
+
     - `-dp 3000:3000` - same as before. Run in detached (background) mode and create a port mapping
     - `-w /app` - sets the "working directory" or the current directory that the command will run from
-    - `-v ${PWD}:/app` - bind mount the current directory from the host in the container into the `/app` directory
+    - `-v "$(pwd):/app"` - bind mount the current directory from the host in the container into the `/app` directory
     - `node:12-alpine` - the image to use. Note that this is the base image for our app from the Dockerfile
     - `sh -c "yarn install && yarn run dev"` - the command. We're starting a shell using `sh` (alpine doesn't have `bash`) and
       running `yarn install` to install _all_ dependencies and then running `yarn run dev`. If we look in the `package.json`,

docs/tutorial/using-docker-compose/index.md

@@ -49,11 +49,11 @@ And now, we'll start migrating a service at a time into the compose file.
 
 ## Defining the App Service
 
-To remember, this was the command we were using to define our app container (replace the ` \ ` characters with `` ` `` in Windows PowerShell).
+To remember, this was the command we were using to define our app container.
 
 ```bash
 docker run -dp 3000:3000 \
-  -w /app -v ${PWD}:/app \
+  -w /app -v "$(pwd):/app" \
   --network todo-app \
   -e MYSQL_HOST=mysql \
   -e MYSQL_USER=root \
@@ -63,6 +63,20 @@ docker run -dp 3000:3000 \
   sh -c "yarn install && yarn run dev"
 ```
 
+If you are using PowerShell then use this command.
+
+```powershell
+docker run -dp 3000:3000 `
+  -w /app -v "$(pwd):/app" `
+  --network todo-app `
+  -e MYSQL_HOST=mysql `
+  -e MYSQL_USER=root `
+  -e MYSQL_PASSWORD=secret `
+  -e MYSQL_DB=todos `
+  node:12-alpine `
+  sh -c "yarn install && yarn run dev"
+```
+
 1. First, let's define the service entry and the image for the container. We can pick any name for the service. 
    The name will automatically become a network alias, which will be useful when defining our MySQL service.
 
@@ -102,7 +116,7 @@ docker run -dp 3000:3000 \
           - 3000:3000
     ```
 
-1. Next, we'll migrate both the working directory (`-w /app`) and the volume mapping (`-v ${PWD}:/app`) by using
+1. Next, we'll migrate both the working directory (`-w /app`) and the volume mapping (`-v "$(pwd):/app"`) by using
    the `working_dir` and `volumes` definitions. Volumes also has a [short](https://docs.docker.com/compose/compose-file/#short-syntax-3) and [long](https://docs.docker.com/compose/compose-file/#long-syntax-3) syntax.
 
     One advantage of Docker Compose volume definitions is we can use relative paths from the current directory.
@@ -145,7 +159,7 @@ docker run -dp 3000:3000 \
   
 ### Defining the MySQL Service
 
-Now, it's time to define the MySQL service. The command that we used for that container was the following (replace the ` \ ` characters with `` ` `` in Windows PowerShell):
+Now, it's time to define the MySQL service. The command that we used for that container was the following:
 
 ```bash
 docker run -d \
@@ -156,6 +170,17 @@ docker run -d \
   mysql:5.7
 ```
 
+If you are using PowerShell then use this command.
+
+```powershell
+docker run -d `
+  --network todo-app --network-alias mysql `
+  -v todo-mysql-data:/var/lib/mysql `
+  -e MYSQL_ROOT_PASSWORD=secret `
+  -e MYSQL_DATABASE=todos `
+  mysql:5.7
+```
+
 1. We will first define the new service and name it `mysql` so it automatically gets the network alias. We'll
    go ahead and specify the image to use as well.