Add documentation for core Docker concepts and guides (#19691)

* Added the-basic pages
---------

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Co-authored-by: Michael Irwin <mikesir87@gmail.com>
Co-authored-by: Craig Osterhout <103533812+craig-osterhout@users.noreply.github.com>

assets/js/src/alpine.js

@@ -1,9 +1,12 @@
 import Alpine from 'alpinejs'
 import collapse from '@alpinejs/collapse'
+import persist from '@alpinejs/persist'
  
 window.Alpine = Alpine
 
 Alpine.plugin(collapse)
 Alpine.store("showSidebar", false)
 
+Alpine.plugin(persist)
+
 Alpine.start()

content/guides/docker-concepts/the-basics/what-is-a-container.md

@@ -0,0 +1,190 @@
+---
+title: What is a container?
+keywords: concepts, build, images, container, docker desktop
+description: What is a container? This concept page will teach you about containers and provide a quick hands-on where you will run your first container.
+---
+
+{{< youtube-embed W1kWqFkiu7k >}}
+
+## Explanation
+
+Imagine you're developing a killer web app that has three main components - a React frontend, a Python API, and a PostgreSQL database. If you wanted to work on this project, you'd have to install Node, Python, and PostgreSQL. 
+
+How do you make sure you have the same versions as the other developers on your team? Or your CI/CD system? Or what's used in production?
+
+How do you ensure the version of Python (or Node or the database) your app needs isn't affected by what's already on your machine? How do you manage potential conflicts?
+
+Enter containers!
+
+What is a container? Simply put, containers are isolated processes for each of your app's components. Each component - the frontend React app, the Python API engine, and the database - runs in its own isolated environment, completely isolated from everything else on your machine. 
+
+Here's what makes them awesome. Containers are:
+
+- Self-contained. Each container has everything it needs to function with no reliance on any pre-installed dependencies on the host machine.
+- Isolated. Since containers are run in isolation, they have minimal influence on the host and other containers, increasing the security of your applications.
+- Independent. Each container is independently managed. Deleting one container won't affect any others.
+- Portable. Containers can run anywhere! The container that runs on your development machine will work the same way in a data center or anywhere in the cloud!
+
+### Containers versus virtual machines (VMs)
+
+Without getting too deep, a VM is an entire operating system with its own kernel, hardware drivers, programs, and applications. Spinning up a VM only to isolate a single application is a lot of overhead.
+
+A container is simply an isolated process with all of the files it needs to run. If you run multiple containers, they all share the same kernel, allowing you to run more applications on less infrastructure.
+
+> **Using VMs and containers together**
+>
+> Quite often, you will see containers and VMs used together. As an example, in a cloud environment, the provisioned machines are typically VMs. However, instead of provisioning one machine to run one application, a VM with a container runtime can run multiple containerized applications, increasing resource utilization and reducing costs.
+
+
+## Try it now
+
+In this hands-on, you will see how to run a Docker container using the Docker Desktop GUI.
+
+{{< tabs group=concept-usage persist=true >}}
+{{< tab name="Using the GUI" >}}
+
+Use the following instructions to run a container.
+
+1. Open Docker Desktop and select the **Search** field on the top navigation bar.
+
+2. Specify `welcome-to-docker` in the search input and then select the **Pull** button.
+
+    ![A screenshot of the Docker Dashboard showing the search result for welcome-to-docker Docker image ](images/search-the-docker-image.webp?border=true&w=1000&h=700)
+
+3. Once the image is successfully pulled, select the **Run** button.
+
+4. Expand the **Optional settings**.
+
+5. In the **Container name**, specify `welcome-to-docker`.
+
+6. In the **Host port**, specify `8080`.
+
+    ![A screenshot of Docker Dashboard showing the container run dialog with welcome-to-docker typed in as the container name and 8080 specified as the port number](images/run-a-new-container.webp?border=true&w=550&h=400)
+
+7. Select **Run** to start your container.
+
+Congratulations! You just ran your first container! 🎉
+ 
+### View your container
+
+You can view all of your containers by going to the **Containers** view of the Docker Dashboard.
+
+![Screenshot of the container view of the Docker Desktop GUI showing the welcome-to-docker container running on the host port 8080](images/view-your-containers.webp?border=true&w=750&h=600)
+
+This container runs a web server that displays a simple website. When working with more complex projects, you'll run different parts in different containers. For example, you might run a different container for the frontend, backend, and database.
+
+### Access the frontend
+
+When you launched the container, you exposed one of the container's ports onto your machine. Think of this as creating configuration to let you to connect through the isolated environment of the container. 
+
+For this container, the frontend is accessible on port `8080`. To open the website, select the link in the **Port(s)** column of your container or visit [http://localhost:8080](https://localhost:8080) in your browser.
+
+![Screenshot of the landing page coming from the running container](images/access-the-frontend.webp?border)
+
+### Explore your container
+
+Docker Desktop lets you explore and interact with different aspects of your container. Try it out yourself. 
+
+1. Go to the **Containers** view in the Docker Dashboard.
+
+2. Select your container.
+
+3. Select the **Files** tab to explore your container's isolated file system.
+
+    ![Screenshot of the Docker Dashboard showing the files and directories inside a running container](images/explore-your-container.webp?border)
+
+### Stop your container
+
+The `docker/welcome-to-docker` container continues to run until you stop it. 
+
+1. Go to the **Containers** view in the Docker Dashboard.
+
+2. Locate the container you'd like to stop.
+
+3. Select the **Stop** action in the **Actions** column.
+
+    ![Screenshot of the Docker Dashboard with the welcome container selected and being prepared to stop](images/stop-your-container.webp?border)
+
+{{< /tab >}}
+{{< tab name="Using the CLI" >}}
+
+Follow the instructions to run a container using the CLI:
+
+1. Open your CLI terminal and start a container by using the [`docker run`](/reference/cli/docker/container/run/) command:
+
+    ```console
+    $ docker run -d -p 8080:80 docker/welcome-to-docker
+    ```
+
+    The output from this command is the full container ID. 
+
+Congratulations! You just fired up your first container! 🎉
+
+### View your running containers
+
+You can verify if the container is up and running by using the [`docker ps`](/reference/cli/docker/container/ls/) command:
+
+```console
+docker ps
+```
+
+You will see output like the following:
+
+```console
+ CONTAINER ID   IMAGE                      COMMAND                  CREATED          STATUS          PORTS                      NAMES
+ a1f7a4bb3a27   docker/welcome-to-docker   "/docker-entrypoint.…"   11 seconds ago   Up 11 seconds   0.0.0.0:8080->80/tcp       gracious_keldysh
+```
+
+This container runs a web server that displays a simple website. When working with more complex projects, you'll run different parts in different containers. For example, a different container for the `frontend`, `backend`, and `database`.
+
+> **Tip**
+>
+> The `docker ps` command will show you _only_ running containers. To view stopped containers, add the `-a` flag to list all containers: `docker ps -a`
+{ .tip }
+
+
+### Access the frontend
+
+When you launched the container, you exposed one of the container's ports onto your machine. Think of this as creating configuration to let you to connect through the isolated environment of the container. 
+
+For this container, the frontend is accessible on port `8080`. To open the website, select the link in the **Port(s)** column of your container or visit [http://localhost:8080](https://localhost:8080) in your browser.
+
+![Screenshot of the landing page of the Nginx web server, coming from the running container](images/access-the-frontend.webp?border)
+
+### Stop your container
+
+The `docker/welcome-to-docker` container continues to run until you stop it. You can stop a container using the `docker stop` command.
+
+1. Run `docker ps` to get the ID of the container
+
+2. Provide the container ID or name to the [`docker stop`](/reference/cli/docker/container/stop/) command:
+
+    ```console
+    docker stop <the-container-id>
+    ```
+
+> **Tip**
+>
+> When referencing containers by ID, you don't need to provide the full ID. You only need to provide enough of the ID to make it unique. As an example, the previous container could be stopped by running the following command:
+>
+> ```console
+> docker stop a1f
+> ```
+{ .tip }
+
+{{< /tab >}}
+{{< /tabs >}}
+
+## Additional resources
+
+The following links provide additional guidance into containers:
+
+- [Running a container](/engine/reference/run/)
+- [Overview of container](https://www.docker.com/resources/what-container/)
+- [Why Docker?](https://www.docker.com/why-docker/)
+
+## Next steps
+
+Now that you have learned the basics of a Docker container, it's time to learn about Docker images.
+
+{{< button text="What is an image?" url="what-is-an-image" >}}

content/guides/docker-concepts/the-basics/what-is-a-registry.md

@@ -0,0 +1,137 @@
+---
+title: What is a registry?
+keywords: concepts, build, images, container, docker desktop
+description: What is a registry? This Docker Concept will explain what a registry is, explore their interoperability, and have you interact with registries.
+---
+
+{{< youtube-embed 2WDl10Wv5rs >}}
+
+## Explanation
+
+Now that you know what a container image is and how it works, you might wonder - where do you store these images? 
+
+Well, you can store your container images on your computer system, but what if you want to share them with your friends or use them on another machine? That's where the image registry comes in.
+
+An image registry is a centralized location for storing and sharing your container images. It can be either public or private. [Docker Hub](https://hub.docker.com) is a public registry that anyone can use and is the default registry. 
+
+While Docker Hub is a popular option, there are many other available container registries available today, including [Amazon Elastic Container Registry(ECR)](https://aws.amazon.com/ecr/), [Azure Container Registry (ACR)](https://azure.microsoft.com/en-in/products/container-registry), and [Google Container Registry (GCR)](https://cloud.google.com/artifact-registry). You can even run your private registry on your local system or inside your organization. For example, Harbor, JFrog Artifactory, GitLab Container registry etc.
+
+### Registry vs. repository
+
+While you're working with registries, you might hear the terms **registry** and **repository** as if they're interchangeable. Even though they're related, they're not quite the same thing.
+
+A _registry_ is a centralized location that stores and manages container images, whereas a _repository_ is a collection of related container images within a registry. Think of it as a folder where you organize your images based on projects. Each repository contains one or more container images.
+
+>**Note**
+>
+> You can create one private repository and unlimited public repositories using the free version of Docker Hub. For more information, visit the [Docker Hub subscription page](https://www.docker.com/pricing/).
+
+## Try it now
+
+In this hands-on, you will learn how to build and push a Docker image to the Docker Hub repository.
+
+### Sign up for a free Docker account
+
+1. If you haven't created one yet, head over to the [Docker Hub](https://hub.docker.com) page to sign up for a new Docker account.
+
+    ![Screenshot of the official Docker Hub page showing the Sign up page](images/dockerhub-signup.webp?border)
+
+    You can use your Google or GitHub account to authenticate.
+
+### Create your first repository
+
+1. Sign in to [Docker Hub](https://hub.docker.com).
+2. Select the **Create repository** button in the top-right corner.
+3. Select your namespace (most likely your username) and enter `docker-quickstart` as the repository name.
+
+    ![Screenshot of the Docker Hub page that shows how to create a public repository](images/create-hub-repository.webp?border)
+
+4. Set the visibility to **Public**. 
+5. Select the **Create** button to create the repository.
+
+That's it. You've successfully created your first repository. 🎉
+
+This repository is empty right now. You'll now fix this by pushing an image to it.
+
+### Sign in with Docker Desktop
+
+1. [Download and install](https://www.docker.com/products/docker-desktop/) Docker Desktop, if not already installed.
+2. In the Docker Desktop GUI, select the **Sign in** button in the top-right corner
+
+### Clone sample Node.js code
+
+In order to create an image, you first need a project. To get you started quickly, you'll use a sample Node.js project found at [github.com/dockersamples/helloworld-demo-node](https://github.com/dockersamples/helloworld-demo-node). This repository contains a pre-built Dockerfile necessary for building a Docker image.
+
+Don't worry about the specifics of the Dockerfile, as you'll learn about that in later sections.
+
+1. Clone the GitHub repository using the following command:
+
+    ```console
+    git clone https://github.com/dockersamples/helloworld-demo-node
+    ```
+
+2. Navigate into the newly created directory.
+
+    ```console
+    cd hello-world-demo-node
+    ```
+
+3. Run the following command to build a Docker image, swapping out `YOUR_DOCKER_USERNAME` with your username.
+
+    ```console
+    docker build -t <YOUR_DOCKER_USERNAME>/docker-quickstart .
+    ```
+
+    >**Note**
+    >
+    > Make sure you include the dot (.) at the end of the `docker build` command. This tells Docker where to find the Dockerfile.
+
+4. Run the following command to list the newly created Docker image:
+
+    ```console
+    docker images
+    ```
+
+    You will see output like the following:
+
+    ```console
+    REPOSITORY                                 TAG       IMAGE ID       CREATED         SIZE
+    <YOUR_DOCKER_USERNAME>/docker-quickstart   latest    476de364f70e   2 minutes ago   170MB
+    ```
+
+5. Start a container to test the image by running the following command (swap out the username with your own username):
+
+    ```console
+    docker run -d -p 8080:8080 <YOUR_DOCKER_USERNAME>/docker-quickstart 
+    ```
+
+    You can verify if the container is working by visiting [http://localhost:8080](http://localhost:8080) with your browser.
+
+6. Use the [`docker tag`](/reference/cli/docker/image/tag/) command to tag the Docker image. Docker tags allow you to label and version your images. 
+
+    ```console 
+    docker tag <YOUR_DOCKER_USERNAME>/docker-quickstart <YOUR_DOCKER_USERNAME>/docker-quickstart:1.0 
+    ```
+
+7. Finally, it's time to push the newly built image to your Docker Hub repository by using the [`docker push`](/reference/cli/docker/image/push/) command:
+
+    ```console 
+    docker push -u <YOUR_DOCKER_USERNAME>/docker-quickstart:1.0
+    ```
+
+8. Open [Docker Hub](https://hub.docker.com) and navigate to your repository. Navigate to the **Tags** section and see your newly pushed image.
+
+    ![Screenshot of the Docker Hub page that displays the newly added image tag](images/dockerhub-tags.webp?border=true) 
+
+In this walkthrough, you signed up for a Docker account, created your first Docker Hub repository, and built, tagged, and pushed a container image to your Docker Hub repository.
+
+## Additional resources
+
+- [Docker Hub Quickstart](/docker-hub/quickstart/)
+- [Manage Docker Hub Repositories](/docker-hub/repos/)
+
+## Next steps
+
+Now that you understand the basics of containers and images, you're ready to learn about Docker Compose.
+
+{{< button text="What is Docker Compose?" url="what-is-Docker-Compose" >}}

content/guides/docker-concepts/the-basics/what-is-an-image.md

@@ -0,0 +1,207 @@
+---
+title: What is an image?
+keywords: concepts, build, images, container, docker desktop
+description: What is an image
+---
+
+{{< youtube-embed NyvT9REqLe4 >}}
+
+## Explanation
+
+Seeing a [container](./what-is-a-container) is an isolated process, where does it get its files and configuration? How do you share those environments? 
+
+That's where container images come in! 
+
+A container image is a standardized package that includes all of the files, binaries, libraries, and configurations to run a container.
+
+For a [PostgreSQL](https://hub.docker.com/_/postgresql) image, that image will package the database binaries, config files, and other dependencies. For a Python web app, it'll include the Python runtime, your app code, and all of its dependencies.
+
+There are two important principles of images:
+
+1. Images are immutable. Once an image is created, it can't be modified. You can only make a new image or add changes on top of it.
+
+2. Container images are composed of layers. Each layer represented a set of file system changes that add, remove, or modify files.
+
+These two principles let you to extend or add to existing images. For example, if you are building a Python app, you can start from the [Python image](https://hub.docker.com/_/python) and add additional layers to install your app's dependencies and add your code. This lets you focus on your app, rather than Python itself.
+
+### Finding images
+
+[Docker Hub](https://hub.docker.com) is the default global marketplace for storing and distributing images. It has over 100,000 images created by developers that you can run locally. You can search for Docker Hub images and run them directly from Docker Desktop.
+
+Docker Hub provides a variety of Docker-supported and endorsed images known as Docker Trusted Content. These provide fully managed services or great starters for your own images. These include:
+
+- [Docker Official Images](https://hub.docker.com/search?q=&type=image&image_filter=official) - a curated set of Docker repositories, serve as the starting point for the majority of users, and are some of the most secure on Docker Hub
+- [Docker Verified Publishers](https://hub.docker.com/search?q=&image_filter=store) - high-quality images from commercial publishers verified by Docker
+- [Docker-Sponsored Open Source](https://hub.docker.com/search?q=&image_filter=open_source) - images published and maintained by open-source projects sponsored by Docker through Docker's open source program
+
+For example, [Redis](https://hub.docker.com/_/redis) and [Memcached](https://hub.docker.com/_/memcached) are a few popular ready-to-go Docker Official Images. You can download these images and have these services up and running in a matter of seconds. There are also base images, like the [Node.js](https://hub.docker.com/_/node) Docker image, that you can use as a starting point and add your own files and configurations.
+
+## Try it now
+
+{{< tabs group=concept-usage persist=true >}}
+{{< tab name="Using the GUI" >}}
+
+In this hands-on, you will learn how to search and pull a container image using the Docker Desktop GUI.
+
+### Search for and download an image
+
+1. Open the Docker Dashboard and select the **Images** view in the left-hand navigation menu.
+
+    ![A screenshot of the Docker Dashboard showing the image view on the left sidebar](images/click-image.webp?border=true&w=1050&h=400)
+
+2. Select the **Search images to run** button. If you don't see it, select the _global search bar_ at the top of the screen.
+
+    ![A screenshot of the Docker Dashboard showing the search ta](images/search-image.webp?border)
+
+3. In the **Search** field, enter "welcome-to-docker". Once the search has completed, select the `docker/welcome-to-docker` image.
+
+    ![A screenshot of the Docker Dashboard showing the search results for the docker/welcome-to-docker image](images/select-image.webp?border=true&w=1050&h=400)
+
+4. Select **Pull** to download the image.
+
+
+### Learn about the image
+
+Once you have an image downloaded, you can learn quite a few details about the image either through the GUI or the CLI.
+
+1. In the Docker Dashboard, select the **Images** view.
+
+2. Select the **docker/welcome-to-docker** image to open details about the image.
+
+    ![A screenshot of the Docker Dashboard showing the images view with an arrow pointing to the docker/welcome-to-docker image](images/pulled-image.webp?border=true&w=1050&h=400)
+
+3. The image details page presents you with information regarding the layers of the image, the packages and libraries installed in the image, and any discovered vulnerabilities.
+
+    ![A screenshot of the image details view for the docker/welcome-to-docker image](images/image-layers.webp?border=true&w=1050&h=400)
+
+
+
+{{< /tab >}}
+
+{{< tab name="Using the CLI" >}}
+
+Follow the instructions to search and pull a Docker image using CLI to view its layers.
+
+### Search for and download an image
+
+1. Open a terminal and search for images using the [`docker search`](/reference/cli/docker/search/) command:
+
+    ```console
+    docker search docker/welcome-to-docker
+    ```
+
+    You will see output like the following:
+
+    ```console
+    NAME                       DESCRIPTION                                     STARS     OFFICIAL
+    docker/welcome-to-docker   Docker image for new users getting started w…   20
+    ```
+
+    This output shows you information about relevant images available on Docker Hub.
+
+2. Pull the image using the [`docker pull`](/reference/cli/docker/image/pull/) command.
+
+    ```console
+    docker pull docker/welcome-to-docker
+    ```
+
+    You will see output like the following:
+
+    ```console
+    Using default tag: latest
+    latest: Pulling from docker/welcome-to-docker
+    579b34f0a95b: Download complete
+    d11a451e6399: Download complete
+    1c2214f9937c: Download complete
+    b42a2f288f4d: Download complete
+    54b19e12c655: Download complete
+    1fb28e078240: Download complete
+    94be7e780731: Download complete
+    89578ce72c35: Download complete
+    Digest: sha256:eedaff45e3c78538087bdd9dc7afafac7e110061bbdd836af4104b10f10ab693
+    Status: Downloaded newer image for docker/welcome-to-docker:latest
+    docker.io/docker/welcome-to-docker:latest
+    ```
+
+    Each of line represents a different downloaded layer of the image. Remember that each layer is a set of filesystem changes and provides functionality of the image.
+
+
+### Learn about the image
+
+1. List your downloaded images using the [`docker image ls`](/reference/cli/docker/image/ls/) command:
+
+    ```console
+    docker image ls
+    ```
+
+    You will see output like the following:
+
+    ```console
+    REPOSITORY                 TAG       IMAGE ID       CREATED        SIZE
+    docker/welcome-to-docker   latest    eedaff45e3c7   4 months ago   29.7MB
+    ```
+
+    The command shows a list of Docker images currently available on your system. The `docker/welcome-to-docker` has a total size of approximately 29.7MB.
+
+    > **Image size**
+    > 
+    > The image size represented here reflects the uncompressed size of the image, not the download size of the layers.
+
+2. List the image's layers using the [`docker image history`](/reference/cli/docker/image/history/) command:
+
+    ```console
+    docker image history docker/welcome-to-docker
+    ```
+
+    You will see output like the following:
+
+    ```console
+    IMAGE          CREATED        CREATED BY                                      SIZE      COMMENT
+    648f93a1ba7d   4 months ago   COPY /app/build /usr/share/nginx/html # buil…   1.6MB     buildkit.dockerfile.v0
+    <missing>      5 months ago   /bin/sh -c #(nop)  CMD ["nginx" "-g" "daemon…   0B
+    <missing>      5 months ago   /bin/sh -c #(nop)  STOPSIGNAL SIGQUIT           0B
+    <missing>      5 months ago   /bin/sh -c #(nop)  EXPOSE 80                    0B
+    <missing>      5 months ago   /bin/sh -c #(nop)  ENTRYPOINT ["/docker-entr…   0B
+    <missing>      5 months ago   /bin/sh -c #(nop) COPY file:9e3b2b63db9f8fc7…   4.62kB
+    <missing>      5 months ago   /bin/sh -c #(nop) COPY file:57846632accc8975…   3.02kB
+    <missing>      5 months ago   /bin/sh -c #(nop) COPY file:3b1b9915b7dd898a…   298B
+    <missing>      5 months ago   /bin/sh -c #(nop) COPY file:caec368f5a54f70a…   2.12kB
+    <missing>      5 months ago   /bin/sh -c #(nop) COPY file:01e75c6dd0ce317d…   1.62kB
+    <missing>      5 months ago   /bin/sh -c set -x     && addgroup -g 101 -S …   9.7MB
+    <missing>      5 months ago   /bin/sh -c #(nop)  ENV PKG_RELEASE=1            0B
+    <missing>      5 months ago   /bin/sh -c #(nop)  ENV NGINX_VERSION=1.25.3     0B
+    <missing>      5 months ago   /bin/sh -c #(nop)  LABEL maintainer=NGINX Do…   0B
+    <missing>      5 months ago   /bin/sh -c #(nop)  CMD ["/bin/sh"]              0B
+    <missing>      5 months ago   /bin/sh -c #(nop) ADD file:ff3112828967e8004…   7.66MB
+    ```
+
+    This output shows you all of the layers, their sizes, and the command used to create the layer. 
+
+    > **Viewing the full command**
+    >
+    > If you add the `--no-trunc` flag to the command, you will see the full command. Note that, since the output is in a table-like format, longer commands will cause the output to be very difficult to navigate.
+    { .tip }
+
+
+{{< /tab >}}
+{{< /tabs >}}
+
+In this walkthrough, you searched and pulled a Docker image. In addition to pulling a Docker image, you also learned about the layers of a Docker Image.
+
+## Additional resources
+
+The following resources will help you learn more about exploring, finding, and building images:
+
+- [Docker Trusted Content](/trusted-content/)
+  - [Docker Official Images docs](/trusted-content/official-images/)
+  - [Docker Verified Publisher docs](/trusted-content/dvp-program/)
+  - [Docker-Sponsored Open Source Program docs](/trusted-content/dsos-program/)
+- [Explore the Image view in Docker Desktop](/desktop/use-desktop/images/)
+- [Packaging your software](/build/building/packaging/)
+- [Docker Hub](https://hub.docker.com)
+
+## Next steps
+
+Now that you have learned the basics of images, it's time to learn about distributing images through registries.
+
+{{< button text="What is a registry?" url="what-is-a-registry" >}}

content/guides/docker-concepts/the-basics/what-is-docker-compose.md

@@ -0,0 +1,137 @@
+---
+title: What is Docker Compose?
+keywords: concepts, build, images, container, docker desktop
+description: What is Docker Compose?
+---
+
+{{< youtube-embed xhcUIK4fGtY >}}
+
+## Explanation
+
+If you've been following the guides so far, you've been working with single container applications. But, now you're wanting to do something more complicated - run databases, message queues, caches, or a variety of other services. Do you install everything in a single container? Run multiple containers? If you run multiple, how do you connect them all together?
+
+One best practice for containers is that each container should do one thing and do it well. While there are exceptions to this rule, avoid the tendency to have one container do multiple things.
+
+You can use multiple `docker run` commands to start multiple containers. But, you'll soon realize you'll need to manage networks, all of the flags needed to connect containers to those networks, and more. And when you're done, cleanup is a little more complicated.
+
+With Docker Compose, you can define all of your containers and their configurations in a single YAML file. If you include this file in your code repository, anyone that clones your repository can get up and running with a single command.
+
+It's important to understand that Compose is a declarative tool - you simply define it and go. You don't always need to recreate everything from scratch. If you make a change, run `docker compose up` again and Compose will reconcile the changes in your file and apply them intelligently.
+
+> **Dockerfile versus Compose file**
+>
+> A Dockerfile provides instructions to build a container image while a Compose file defines your running containers. Quite often, a Compose file references a Dockerfile to build an image to use for a particular service.
+
+
+## Try it out 
+
+In this hands-on, you will learn how to use a Docker Compose to run a multi-container application. You'll use a simple to-do list app built with Node.js and MySQL as a database server.
+
+### Start the application
+
+Follow the instructions to run the to-do list app on your system.
+
+1. [Download and install](https://www.docker.com/products/docker-desktop/) Docker Desktop.
+2. Open a terminal and [clone this sample application](https://github.com/dockersamples/todo-list-app).
+
+    ```console
+    git clone https://github.com/dockersamples/todo-list-app 
+    ```
+
+3. Navigate into the `todo-list-app` directory:
+
+    ```console
+    cd todo-list-app
+    ```
+
+    Inside this directory, you'll find a file named `compose.yaml`. This YAML file is where all the magic happens! It defines all the services that make up your application, along with their configurations. Each service specifies its image, ports, volumes, networks, and any other settings necessary for its functionality. Take some time to explore the YAML file and familiarize yourself with its structure. 
+
+4. Use the [`docker compose up`](/reference/cli/docker/compose/up/) command to start the application:
+
+    ```console
+    docker compose up -d --build
+    ```
+
+    When you run this command, you should see an output like this:
+
+    ```console
+    [+] Running 4/4
+    ✔ app 3 layers [⣿⣿⣿]      0B/0B            Pulled           7.1s
+      ✔ e6f4e57cc59e Download complete                          0.9s
+      ✔ df998480d81d Download complete                          1.0s
+      ✔ 31e174fedd23 Download complete                          2.5s
+    [+] Running 2/4
+      ⠸ Network todo-list-app_default           Created         0.3s
+      ⠸ Volume "todo-list-app_todo-mysql-data"  Created         0.3s
+      ✔ Container todo-list-app-app-1           Started         0.3s
+      ✔ Container todo-list-app-mysql-1         Started         0.3s
+    ```
+
+    A lot happened here! A couple of things to call out:
+
+    - Two container images were downloaded from Docker Hub - node and MySQL
+    - A network was created for your application
+    - A volume was created to persist the database files between container restarts
+    - Two containers were started with all of their necessary config
+
+    If this feels overwhelming, don't worry! You'll get there!
+
+5. With everything now up and running, you can open [http://localhost:3000](http://localhost:3000) in your browser to see the site. Feel free to add items to the list, check them off, and remove them.
+
+    ![A screenshot of a webpage showing the todo-list application running on port 3000](images/todo-list-app.webp?border=true&w=950&h=400)
+
+6. If you look at the Docker Desktop GUI, you can see the containers and dive deeper into their configuration.
+
+    ![A screenshot of Docker Desktop dashboard showing the list of containers running todo-list app](images/todo-list-containers.webp?border=true&w=950&h=400)
+
+
+### Tear it down
+
+Since this application was started using Docker Compose, it's easy to tear it all down when you're done.
+
+1. In the CLI, use the [`docker compose down`](/reference/cli/docker/compose/down/) command to remove everything:
+
+    ```console
+    docker compose down
+    ```
+
+    You'll see output similar to the following:
+
+    ```console
+    [+] Running 2/2
+    ✔ Container todo-list-app-mysql-1  Removed        2.9s
+    ✔ Container todo-list-app-app-1    Removed        0.1s
+    ✔ Network todo-list-app_default    Removed        0.1s
+    ```
+
+    > **Volume persistence**
+    >
+    > By default, volumes _aren't_ automatically removed when you tear down a Compose stack. The idea is that you might want the data back if you start the stack again.
+    >
+    > If you do want to remove the volumes, add the `--volumes` flag when running the `docker compose down` command:
+    >
+    > ```console
+    > docker compose down --volumes
+    > ```
+    { .tip }
+
+2. Alternatively, you can use the Docker Desktop GUI to remove the containers by selecting the application stack and selecting the **Delete** button.
+
+    ![A screenshot of the Docker Desktop GUI showing the containers view with an arrow pointing to the "Delete" button](images/todo-list-delete.webp?w=930&h=400)
+
+    > **Using the GUI for Compose stacks**
+    >
+    > Note that if you remove the containers for a Compose app in the GUI, it's removing only the containers. You'll have to manually remove the network and volumes if you want to do so.
+    { .important }
+
+In this walkthrough, you learned how to use Docker Compose to start and stop a multi-container application.
+
+
+## Additional resources
+
+This page was a brief introduction to Compose. In the following resources, you can dive deeper into Compose and how to write Compose files.
+
+
+* [Overview of Docker Compose](/compose/)
+* [Overview of Docker Compose CLI](/compose/reference/)
+* [How Compose works](/compose/compose-application-model/)

data/toc.yaml

@@ -46,6 +46,20 @@ Guides:
       - title: "Part 10: What next?"
         path: /get-started/11_what_next/
 
+- sectiontitle: "Docker concepts"
+  section:
+  - sectiontitle: "The basics"
+    section:
+    - title: "What is a container?"
+      path: /guides/docker-concepts/the-basics/what-is-a-container/
+    - title: "What is an image?"
+      path: /guides/docker-concepts/the-basics/what-is-an-image/
+    - title: "What is a registry?"
+      path: /guides/docker-concepts/the-basics/what-is-a-registry/
+    - title: "What is Docker Compose?"
+      path: /guides/docker-concepts/the-basics/what-is-docker-compose/
+
+
 - sectiontitle: Language-specific guides
   section:
   - path: /language/

hugo_stats.json

@@ -75,6 +75,8 @@
       "PowerShell",
       "PowerShell-CLI",
       "Python",
+      "RHEL-8",
+      "RHEL-9",
       "Raw",
       "React",
       "Remote-file",
@@ -86,6 +88,8 @@
       "Ubuntu",
       "Unix-pipe",
       "Use-OpenAI",
+      "Using-the-CLI",
+      "Using-the-GUI",
       "Version-4.15-4.17",
       "Version-4.17-and-earlier",
       "Version-4.18-and-later",

layouts/partials/head.html

@@ -44,7 +44,6 @@
 {{ $js := resources.Match "js/src/**.js"
   | resources.Concat "scripts.js"
   | js.Build (dict
-    "minify" true
     "params" (dict
       "apikey" site.Params.algolia.apikey
       "appid" site.Params.algolia.appid

layouts/shortcodes/tabs.html

@@ -1,16 +1,23 @@
 {{ with .Inner }}{{/* don't do anything, just call it */}}{{ end }}
-{{ $default := (index (.Scratch.Get "tabs") 0).name }}
+{{ $first := urlize (index (.Scratch.Get "tabs") 0).name }}
 {{ $group := .Get "group" }}
-
+{{ $groupID := fmt.Printf "tabgroup-%s" (urlize $group) }}
+{{ $persist := .Get "persist" }}
 
 <div
-  x-data="{ selected: '{{ $default | urlize }}' }"
   {{ with $group }}
-    @tab-select.window="$event.detail.group === '{{ . }}' ? selected =
-    $event.detail.name : null"
+    {{ if $persist }}
+      x-data="{ selected: $persist('{{$first}}').as('{{$groupID}}') }"
+    {{ else }}
+      x-data="{ selected: '{{$first}}' }"
+    {{ end }}
+    @tab-select.window="$event.detail.group === '{{ . }}'
+      ? selected = $event.detail.name
+      : null"
+  {{ else }}
+    x-data="{ selected: '{{ $first }}' }"
   {{ end }}
-  aria-role="tabpanel"
->
+  aria-role="tabpanel">
   <div aria-role="tablist" class="space-x-2">
     {{ range (.Scratch.Get "tabs") }}
       <button

layouts/shortcodes/youtube-embed.html

@@ -0,0 +1,7 @@
+<iframe 
+  class="aspect-video w-full"
+  src="https://www.youtube.com/embed/{{ .Get 0 }}?rel=0" 
+  title="YouTube video player" 
+  frameborder="0" 
+  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" 
+  allowfullscreen></iframe>

package-lock.json

@@ -10,6 +10,7 @@
       "license": "Apache License 2.0",
       "dependencies": {
         "@alpinejs/collapse": "^3.13.5",
+        "@alpinejs/persist": "^3.13.5",
         "@docsearch/js": "^3.5.2",
         "@floating-ui/dom": "^1.6.3",
         "@material-symbols/svg-400": "^0.14.6",
@@ -200,6 +201,17 @@
       "resolved": "https://registry.npmjs.org/@alpinejs/collapse/-/collapse-3.13.5.tgz",
       "integrity": "sha512-LHtSF/T3Zrhr0WOeVm4ebdXNH6ftqoZMbmkBTU1n/j8r0joV3oLUsPCyn5qOU8+27d2P/N2a057etOm0MH60oQ=="
     },
+    "node_modules/@alpinejs/persist": {
+      "version": "3.13.5",
+      "resolved": "https://registry.npmjs.org/@alpinejs/persist/-/persist-3.13.5.tgz",
+      "integrity": "sha512-nmULi5Kp/v5/h4FtGpqyzzMPlulc2fmQ+Olhk0NwTcBKSCZDg6OtXgS998rnHpcWO0jsjCmvXn/Pul2av7D8lA=="
+    },
+    "node_modules/@braintree/sanitize-url": {
+      "version": "6.0.4",
+      "resolved": "https://registry.npmjs.org/@braintree/sanitize-url/-/sanitize-url-6.0.4.tgz",
+      "integrity": "sha512-s3jaWicZd0pkP0jf5ysyHUI/RE7MHos6qlToFcGWXVp+ykHOy77OUMrfbgJ9it2C5bow7OIQwYYaHjk9XlBQ2A==",
+      "dev": true
+    },
     "node_modules/@docsearch/css": {
       "version": "3.5.2",
       "resolved": "https://registry.npmjs.org/@docsearch/css/-/css-3.5.2.tgz",

package.json

@@ -15,6 +15,7 @@
   "homepage": "https://docs.docker.com/",
   "dependencies": {
     "@alpinejs/collapse": "^3.13.5",
+    "@alpinejs/persist": "^3.13.5",
     "@docsearch/js": "^3.5.2",
     "@floating-ui/dom": "^1.6.3",
     "@material-symbols/svg-400": "^0.14.6",