Merge pull request #107 from kieran6roberts/docs-wording-improvements

changed some of docs text/wording to improve readability
This commit is contained in:
Michael Irwin 2022-11-28 17:55:13 -05:00 committed by GitHub
commit b4d6426abc
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 26 additions and 24 deletions

View File

@ -1,12 +1,13 @@
# Docker Getting Started Tutorial
This tutorial has been written with the intent of helping folks get up and running
This tutorial was written with the intent of helping folks get up and running
with containers and is designed to work with Docker Desktop. While not going too much
into depth, it covers the following topics:
- Running your first container
- Building containers
- Learning what containers are running and removing them
- Learning what containers are
- Running and removing containers
- Using volumes to persist data
- Using bind mounts to support development
- Using container networking to support multi-container applications
@ -37,6 +38,7 @@ docker compose up
If you find typos or other issues with the tutorial, feel free to create a PR and suggest fixes!
If you have ideas on how to make the tutorial better or new content, please open an issue first before working on your idea. While we love input, we want to keep the tutorial scoped to newcomers.
If you have ideas on how to make the tutorial better or want to suggest adding new content, please open an
issue first before working on your idea. While we love input, we want to keep the tutorial scoped to new-comers.
As such, we may reject ideas for more advanced requests and don't want you to lose any work you might
have done. So, ask first and we'll gladly hear your thoughts!

View File

@ -44,7 +44,7 @@ to scan all newly pushed images automatically, and you can then see the results
## Image Layering
Did you know that you can look at what makes up an image? Using the `docker image history`
Did you know that you can look at how an image is composed? Using the `docker image history`
command, you can see the command that was used to create each layer within an image.
1. Use the `docker image history` command to see the layers in the `getting-started` image you
@ -73,8 +73,8 @@ command, you can see the command that was used to create each layer within an im
<missing> 11 days ago /bin/sh -c #(nop) ADD file:57d621536158358b1… 5.29MB
```
Each of the lines represents a layer in the image. The display here shows the base at the bottom with
the newest layer at the top. Using this, you can also quickly see the size of each layer, helping
Each line represents a layer in the image. The display here shows the base at the bottom with
the newest layer at the top. Using this you can also quickly see the size of each layer, helping to
diagnose large images.
1. You'll notice that several of the lines are truncated. If you add the `--no-trunc` flag, you'll get the
@ -107,7 +107,7 @@ You might remember that when we made a change to the image, the yarn dependencie
way to fix this? It doesn't make much sense to ship around the same dependencies every time we build, right?
To fix this, we need to restructure our Dockerfile to help support the caching of the dependencies. For Node-based
applications, those dependencies are defined in the `package.json` file. So, what if we copied only that file in first,
applications, those dependencies are defined in the `package.json` file. So what if we start by copying only that file in first,
install the dependencies, and _then_ copy in everything else? Then, we only recreate the yarn dependencies if there was
a change to the `package.json`. Make sense?
@ -131,9 +131,9 @@ a change to the `package.json`. Make sense?
`.dockerignore` files are an easy way to selectively copy only image relevant files.
You can read more about this
[here](https://docs.docker.com/engine/reference/builder/#dockerignore-file).
In this case, the `node_modules` folder should be omitted in the second `COPY` step because otherwise,
In this case, the `node_modules` folder should be omitted in the second `COPY` step because otherwise
it would possibly overwrite files which were created by the command in the `RUN` step.
For further details on why this is recommended for Node.js applications and other best practices,
For further details on why this is recommended for Node.js applications as well as further best practices,
have a look at their guide on
[Dockerizing a Node.js web app](https://nodejs.org/en/docs/guides/nodejs-docker-webapp/).
@ -191,7 +191,7 @@ a change to the `package.json`. Make sense?
=> => naming to docker.io/library/getting-started 0.0s
```
First off, you should notice that the build was MUCH faster! And, you'll see that several steps are using
First off, you should notice that the build was MUCH faster! You'll see that several steps are using
previously cached layers. So, hooray! We're using the build cache. Pushing and pulling this image and updates to it
will be much faster as well. Hooray!
@ -199,7 +199,7 @@ a change to the `package.json`. Make sense?
## Multi-Stage Builds
While we're not going to dive into it too much in this tutorial, multi-stage builds are an incredibly powerful
tool to help use multiple stages to create an image. There are several advantages for them:
tool which help us by using multiple stages to create an image. They offer several advantages including:
- Separate build-time dependencies from runtime dependencies
- Reduce overall image size by shipping _only_ what your app needs to run
@ -207,7 +207,7 @@ tool to help use multiple stages to create an image. There are several advantage
### Maven/Tomcat Example
When building Java-based applications, a JDK is needed to compile the source code to Java bytecode. However,
that JDK isn't needed in production. Also, you might be using tools like Maven or Gradle to help build the app.
that JDK isn't needed in production. You might also be using tools such as Maven or Gradle to help build the app.
Those also aren't needed in our final image. Multi-stage builds help.
```dockerfile
@ -220,7 +220,7 @@ FROM tomcat
COPY --from=build /app/target/file.war /usr/local/tomcat/webapps
```
In this example, we use one stage (called `build`) to perform the actual Java build using Maven. In the second
In this example, we use one stage (called `build`) to perform the actual Java build with Maven. In the second
stage (starting at `FROM tomcat`), we copy in files from the `build` stage. The final image is only the last stage
being created (which can be overridden using the `--target` flag).
@ -228,7 +228,7 @@ being created (which can be overridden using the `--target` flag).
### React Example
When building React applications, we need a Node environment to compile the JS code (typically JSX), SASS stylesheets,
and more into static HTML, JS, and CSS. If we aren't doing server-side rendering, we don't even need a Node environment
and more into static HTML, JS, and CSS. Although if we aren't performing server-side rendering, we don't even need a Node environment
for our production build. Why not ship the static resources in a static nginx container?
```dockerfile

View File

@ -27,10 +27,9 @@ You'll notice a few flags being used. Here's some more info on them:
## 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. It gives you quick
access to container logs, lets you get a shell inside the container, and lets you
easily manage container lifecycle (stop, remove, etc.).
Before going any further, we want to highlight the Docker Dashboard, which gives
you a quick view of the containers running on your machine. It provides you
access to container logs, lets you get a shell inside the container, and allows you to easily manage container lifecycle (stop, remove, etc.).
To access the dashboard, follow the instructions in the
[Docker Desktop manual](https://docs.docker.com/desktop/). If you open the dashboard
@ -42,12 +41,13 @@ randomly created name. So, you'll most likely have a different name.
## What is a container?
Now that you've run a container, what _is_ a container? Simply put, a container is
simply another process on your machine that has been isolated from all other processes
Now that you've successfully run a container, let's ask ourselves what _is_ a container? Simply put, a container is
another process on your machine that has been 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.
!!! info "Creating Containers from Scratch"
!!! info
"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 she makes
a simple container, this talk doesn't go into networking, using images for the filesystem,
@ -58,8 +58,8 @@ in Linux for a long time. Docker has worked to make these capabilities approacha
## 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, configuration, scripts, binaries, etc. The
by a **container image**. Since the image contains the container's filesystem, it must include everything
needed to run the application - all dependencies, configuration, scripts, binaries, etc. The
image also contains other configuration for the container, such as environment variables,
a default command to run, and other metadata.
@ -67,6 +67,6 @@ We'll dive deeper into images later on, covering topics such as layering, best p
!!! info
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
filesystem is simply coming from the image whereas a container adds additional isolation that is not
available when simply using chroot.