diff --git a/content/get-started/_index.md b/content/get-started/_index.md index 4638c73d5b3..071abfc1cba 100644 --- a/content/get-started/_index.md +++ b/content/get-started/_index.md @@ -58,11 +58,6 @@ aliases: - /windows/step_six/ - /windows/step_three/ - /windows/step_two/ -- /get-started/what-is-a-container/ -- /get-started/run-your-own-container/ -- /get-started/run-docker-hub-images/ -- /get-started/publish-your-own-image/ -- /get-started/hands-on-overview/ --- This guide contains step-by-step instructions on how to get started with Docker. This guide shows you how to: @@ -72,6 +67,12 @@ This guide contains step-by-step instructions on how to get started with Docker. - Deploy Docker applications using multiple containers with a database. - Run applications using Docker Compose. +> **Note** +> +> Before diving in, try the 5-minute hands-on +> [walkthroughs](../guides/walkthroughs/_index.md) to get more familiar with +> Docker Desktop. + ## What is a container? A container is a sandboxed process running on a host machine that is isolated from all other processes running on that host machine. That isolation leverages [kernel namespaces and cgroups](https://medium.com/@saschagrunert/demystifying-containers-part-i-kernel-space-2c53d6979504), diff --git a/content/guides/walkthroughs/_index.md b/content/guides/walkthroughs/_index.md new file mode 100644 index 00000000000..1147c449d12 --- /dev/null +++ b/content/guides/walkthroughs/_index.md @@ -0,0 +1,36 @@ +--- +title: Walkthroughs overview +keywords: get started, quick start, intro, concepts +description: Learn how to build, share, and run applications faster with Docker's 5-minute hands-on walkthroughs +grid: + - title: "What is a container?" + description: Explore a running container in Docker Desktop + link: "/guides/walkthroughs/what-is-a-container/" + - title: "How do I run a container?" + description: Learn how to build an image and run it as a container + link: "/guides/walkthroughs/run-a-container/" + - title: "Run Docker Hub images" + description: Access over 100,000 images in Docker Hub and learn how to run them as a container + link: "/guides/walkthroughs/run-hub-images/" + - title: "Run multi-container applications" + description: Use Docker Compose to run multi-container applications + link: "/guides/walkthroughs/multi-container-apps/" + - title: "Persist data between containers" + description: Persist and share data among containers using a named volume + link: "/guides/walkthroughs/persist-data/" + - title: "Access a local folder" + description: Share and access a local folder from a container with a bind mount + link: "/guides/walkthroughs/access-local-folder/" + - title: "Containerize your application" + description: Find out how to containerize your own apps with a single command + link: "/guides/walkthroughs/containerize-your-app/" + - title: "Publish your image" + description: Publish and share you images on Docker Hub + link: "/guides/walkthroughs/publish-your-image/" +aliases: +- /get-started/hands-on-overview/ +--- + +Get introduced to Docker Desktop in these 5-minute hands-on guides. + +{{< grid >}} \ No newline at end of file diff --git a/content/guides/walkthroughs/access-local-folder.md b/content/guides/walkthroughs/access-local-folder.md new file mode 100644 index 00000000000..df9213c178a --- /dev/null +++ b/content/guides/walkthroughs/access-local-folder.md @@ -0,0 +1,90 @@ +--- +title: Access a local folder from a container +keywords: get started, quick start, intro, concepts +description: Learn how to access a local folder from a container +--- + +This walkthrough shows you how to access a local folder from a container. To better understand some concepts in this walkthrough, complete the [Run multi-container applications](./multi-container-apps.md) walkthrough first. + +Docker isolates all content, code, and data in a container from your local filesystem. By default, containers can't access directories in your local filesystem. + +![Data isolation diagram](images/getting-started-isolation.webp?w=400) + +Sometimes, you may want to access a directory from your local filesystem. To do this, you can use bind mounts. + +Before you start, [get Docker Desktop](../../get-docker.md). + +## Step 1: Get the sample application + +If you have git, you can clone the repository for the sample application. Otherwise, you can download the sample application. Choose one of the following options. + +{{< tabs >}} +{{< tab name="Clone with git" >}} + +Use the following command in a terminal to clone the sample application repository. + +```console +$ git clone https://github.com/docker/bindmount-apps +``` + +{{< /tab >}} +{{< tab name="Download" >}} + +Download the source and extract it. + +{{< button url="https://github.com/docker/bindmount-apps/archive/refs/heads/main.zip" text="Download the source" >}} + +{{< /tab >}} +{{< /tabs >}} + +## Step 2: Add a bind mount using Compose + +Add a bind mount to access data on your system from a container. A bind mount lets you share a directory from your host's filesystem into the container. + +![Bind mount diagram](images/getting-started-bindmount.webp?w=400) + +To add a bind mount to this project, open the `compose.yaml` file in a code or text editor, and then uncomment the following lines. + +```yaml +todo-app: + # ... + volumes: + - ./app:/usr/src/app + - /usr/src/app/node_modules + +``` + +The `volumes` element tells Compose to mount the local folder `./app` to `/usr/src/app` in the container for the `todo-app` service. This particular bind mount overwrites the static contents of the `/usr/src/app` directory in the container and creates what is known as a development container. The second instruction, `/usr/src/app/node_modules`, prevents the bind mount from overwriting the container's `node_modules` directory to preserve the packages installed in the container. + +## Step 3: Run the application + +In a terminal, run the follow commands to bring up your application. Replace `/path/to/multi-container-app/` with the path to your applications directory. + +{{< include "open-terminal.md" >}} + +```console +$ cd /path/to/multi-container-app/ +``` +```console +$ docker compose up -d +``` + +## Step 4: Develop the application + +Now, you can take advantage of the container’s environment while you develop the application on your local system. Any changes you make to the application on your local system are reflected in the container. In your local directory, open `app/views/todos.ejs` in an code or text editor, update the `Enter your task` string, and save the file. Visit or refresh [localhost:3001](https://localhost:3001)⁠ to view the changes. + +## Summary + +In this walkthrough, you added a bind mount to access a local folder from a container. You can use this to develop faster without having to rebuild your container when updating your code. + +Related information: + +- Deep dive into [bind mounts](../../storage/bind-mounts.md) +- Learn about using bind mounts in Compose in the [Compose file reference](../../compose/compose-file/_index.md) +- Explore using bind mounts via the CLI in the [Docker run reference](/engine/reference/run/#volume-shared-filesystems) + +## Next steps + +Continue to the next walkthrough to learn how you can containerize your own application. + +{{< button url="./containerize-your-app.md" text="Containerize your app" >}} \ No newline at end of file diff --git a/content/guides/walkthroughs/containerize-your-app.md b/content/guides/walkthroughs/containerize-your-app.md new file mode 100644 index 00000000000..c4174d9f788 --- /dev/null +++ b/content/guides/walkthroughs/containerize-your-app.md @@ -0,0 +1,58 @@ +--- +title: Containerize your application +keywords: get started, quick start, intro, concepts +description: Learn how to containerize your application. +--- + +When working with containers, you typically need to create a `Dockerfile` to define your image and a `compose.yaml` file to define how to run it. + +To help you create these files, Docker Desktop has the `docker init` command. Run this command in a terminal within your project folder. `docker init` creates all the required files to containerize your application. This walkthrough shows you how this works. + +Before you start, [get Docker Desktop](../../get-docker.md). + +## Step 1: Run the command to create Docker assets + +Choose one of your own applications that you would like to containerize, and in a terminal, run the following commands. Replace `/path/to/your/project/` with the directory containing your project. + +{{< include "open-terminal.md" >}} + +```console +$ cd /path/to/your/project/ +``` +```console +$ docker init +``` + +## Step 2: Follow the on-screen prompts + +`docker init` walks you through a few questions to configure your project with sensible defaults. Specify your answers and press `Enter`. + +## Step 3: Try to run your application + +Once you have answered all the questions, run the following commands in a terminal to run your project. Replace `/path/to/your/project/` with the directory containing your project. + +```console +$ cd /path/to/your/project/ +``` +```console +$ docker compose up +``` + +## Step 4: Update the Docker assets + +The `docker init` command tries its best to do the heavy lifting for you, but sometimes there's some assembly required. In this case, you can refer to the [Dockerfile reference⁠](/engine/reference/builder/) and [Compose file reference](/compose/compose-file/)⁠ to learn how to update the files created by `docker init`. + +## Summary + +In this walkthrough, you learned how to containerize your own application. + +Related information: + +- Read more about [docker init](../../engine/reference/commandline/init.md) +- Learn more about Docker assets in the [Dockerfile reference⁠](/engine/reference/builder/) and [Compose file reference](/compose/compose-file/) + +## Next steps + +Continue to the next walkthrough to learn how to publish an application as an image on Docker Hub. + +{{< button url="./publish-your-image.md" text="Publish your image" >}} \ No newline at end of file diff --git a/content/guides/walkthroughs/images/getting-started-bindmount.webp b/content/guides/walkthroughs/images/getting-started-bindmount.webp new file mode 100644 index 00000000000..17d38e1d243 Binary files /dev/null and b/content/guides/walkthroughs/images/getting-started-bindmount.webp differ diff --git a/content/guides/walkthroughs/images/getting-started-compose.webp b/content/guides/walkthroughs/images/getting-started-compose.webp new file mode 100644 index 00000000000..6702fbbd31f Binary files /dev/null and b/content/guides/walkthroughs/images/getting-started-compose.webp differ diff --git a/content/guides/walkthroughs/images/getting-started-container.webp b/content/guides/walkthroughs/images/getting-started-container.webp new file mode 100644 index 00000000000..06cf1d58acf Binary files /dev/null and b/content/guides/walkthroughs/images/getting-started-container.webp differ diff --git a/content/guides/walkthroughs/images/getting-started-delete-stack.webp b/content/guides/walkthroughs/images/getting-started-delete-stack.webp new file mode 100644 index 00000000000..77648a993f4 Binary files /dev/null and b/content/guides/walkthroughs/images/getting-started-delete-stack.webp differ diff --git a/content/guides/walkthroughs/images/getting-started-dockerfile.webp b/content/guides/walkthroughs/images/getting-started-dockerfile.webp new file mode 100644 index 00000000000..a720ea773ad Binary files /dev/null and b/content/guides/walkthroughs/images/getting-started-dockerfile.webp differ diff --git a/content/guides/walkthroughs/images/getting-started-explore-container.webp b/content/guides/walkthroughs/images/getting-started-explore-container.webp new file mode 100644 index 00000000000..54340202f24 Binary files /dev/null and b/content/guides/walkthroughs/images/getting-started-explore-container.webp differ diff --git a/content/guides/walkthroughs/images/getting-started-frontend-2.webp b/content/guides/walkthroughs/images/getting-started-frontend-2.webp new file mode 100644 index 00000000000..77fe8b2dd2a Binary files /dev/null and b/content/guides/walkthroughs/images/getting-started-frontend-2.webp differ diff --git a/content/guides/walkthroughs/images/getting-started-frontend.webp b/content/guides/walkthroughs/images/getting-started-frontend.webp new file mode 100644 index 00000000000..fb9bab2adbc Binary files /dev/null and b/content/guides/walkthroughs/images/getting-started-frontend.webp differ diff --git a/content/guides/walkthroughs/images/getting-started-isolation.webp b/content/guides/walkthroughs/images/getting-started-isolation.webp new file mode 100644 index 00000000000..786d8a6e25d Binary files /dev/null and b/content/guides/walkthroughs/images/getting-started-isolation.webp differ diff --git a/content/guides/walkthroughs/images/getting-started-multi-container.webp b/content/guides/walkthroughs/images/getting-started-multi-container.webp new file mode 100644 index 00000000000..a4386d25058 Binary files /dev/null and b/content/guides/walkthroughs/images/getting-started-multi-container.webp differ diff --git a/content/guides/walkthroughs/images/getting-started-push.webp b/content/guides/walkthroughs/images/getting-started-push.webp new file mode 100644 index 00000000000..3a34a267501 Binary files /dev/null and b/content/guides/walkthroughs/images/getting-started-push.webp differ diff --git a/content/guides/walkthroughs/images/getting-started-run-image.webp b/content/guides/walkthroughs/images/getting-started-run-image.webp new file mode 100644 index 00000000000..769cc2d21f1 Binary files /dev/null and b/content/guides/walkthroughs/images/getting-started-run-image.webp differ diff --git a/content/guides/walkthroughs/images/getting-started-run-intro.webp b/content/guides/walkthroughs/images/getting-started-run-intro.webp new file mode 100644 index 00000000000..5d5d0a3eb35 Binary files /dev/null and b/content/guides/walkthroughs/images/getting-started-run-intro.webp differ diff --git a/content/guides/walkthroughs/images/getting-started-run.webp b/content/guides/walkthroughs/images/getting-started-run.webp new file mode 100644 index 00000000000..ab947de636b Binary files /dev/null and b/content/guides/walkthroughs/images/getting-started-run.webp differ diff --git a/content/guides/walkthroughs/images/getting-started-search.webp b/content/guides/walkthroughs/images/getting-started-search.webp new file mode 100644 index 00000000000..c5d8ad1cd4d Binary files /dev/null and b/content/guides/walkthroughs/images/getting-started-search.webp differ diff --git a/content/guides/walkthroughs/images/getting-started-setup.webp b/content/guides/walkthroughs/images/getting-started-setup.webp new file mode 100644 index 00000000000..d217e3c7db1 Binary files /dev/null and b/content/guides/walkthroughs/images/getting-started-setup.webp differ diff --git a/content/guides/walkthroughs/images/getting-started-signin.webp b/content/guides/walkthroughs/images/getting-started-signin.webp new file mode 100644 index 00000000000..ce69ba58379 Binary files /dev/null and b/content/guides/walkthroughs/images/getting-started-signin.webp differ diff --git a/content/guides/walkthroughs/images/getting-started-stop.webp b/content/guides/walkthroughs/images/getting-started-stop.webp new file mode 100644 index 00000000000..a9936a38419 Binary files /dev/null and b/content/guides/walkthroughs/images/getting-started-stop.webp differ diff --git a/content/guides/walkthroughs/images/getting-started-view.webp b/content/guides/walkthroughs/images/getting-started-view.webp new file mode 100644 index 00000000000..4849b1ec42e Binary files /dev/null and b/content/guides/walkthroughs/images/getting-started-view.webp differ diff --git a/content/guides/walkthroughs/images/getting-started-volume.webp b/content/guides/walkthroughs/images/getting-started-volume.webp new file mode 100644 index 00000000000..f03d7d2a264 Binary files /dev/null and b/content/guides/walkthroughs/images/getting-started-volume.webp differ diff --git a/content/guides/walkthroughs/multi-container-apps.md b/content/guides/walkthroughs/multi-container-apps.md new file mode 100644 index 00000000000..dd6bdeace29 --- /dev/null +++ b/content/guides/walkthroughs/multi-container-apps.md @@ -0,0 +1,116 @@ +--- +title: Run multi-container applications +keywords: get started, quick start, intro, concepts +description: Learn how to use Docker to run multi-container applications +--- + +If you've already completed the [How do I run a container?](./run-a-container.md) walkthrough, you learned that you must start each container individually. Imagine how great it would be if a tool could start multiple containers with a single command. That tool is Docker Compose. + +Before you start, [get Docker Desktop](../../get-docker.md). + +## Step 1: Get the sample application + +If you have git, you can clone the repository for the sample application. Otherwise, you can download the sample application. Choose one of the following options. + +{{< tabs >}} +{{< tab name="Clone with git" >}} + +Use the following command in a terminal to clone the sample application repository. + +```console +$ git clone https://github.com/docker/multi-container-app +``` + +{{< /tab >}} +{{< tab name="Download" >}} + +Download the source and extract it. + +{{< button url="https://github.com/docker/multi-container-app/archive/refs/heads/main.zip" text="Download the source" >}} + +{{< /tab >}} +{{< /tabs >}} + +The sample application is a simple todo application built using ExpressJS and Node.js. The application saves all todos in a MongoDB database. You don't need to know any of these technologies to continue with the walkthrough. + +![The sample app architecture](images/getting-started-multi-container.webp?w=400) + +## Step 2: Dig into the Compose file + +View the files of the sample application. Notice that it has a `compose.yaml` file. This file tells Docker how to run your application. Open the `compose.yaml` file in a code or text editor to view what it contains. + +![Viewing the Compose file](images/getting-started-compose.webp?w=400) + +## Step 3: Run the application + +To run the multi-container application, open a terminal and run the following commands. Replace `/path/to/multi-container-app/` with the path to your applications directory. + +{{< include "open-terminal.md" >}} + +```console +$ cd /path/to/multi-container-app/ +``` +```console +$ docker compose up -d +``` + +## Step 4: View the frontend and add todos + +In the **Containers** tab of Docker Desktop, you should now have an application stack with two containers running (the todo-app, and todo-database). + +To view the frontend: + +1. In Docker Desktop, expand the application stack in **Containers**. +2. Select the link to port **3000** in the **Port(s)** column or open [https://localhost:3000](https://localhost:3000)⁠. + +Add some todo tasks in the frontend, and then open [https://localhost:3000](https://localhost:3000) in a new browser tab. Notice that the tasks are still visible. + +## Step 5: Develop in your containers + +When developing with Docker, you may need to automatically update and preview your running services as you edit and save your code. You can use Docker Compose Watch for this. + +To run Compose Watch and see the real-time changes: + +1. Open a terminal and run the following commands. Replace `/path/to/multi-container-app/` with the path to your applications directory. + ```console + $ cd /path/to/multi-container-app/ + ``` + ```console + $ docker compose watch + ``` +2. Open `app/views/todos.ejs` in a text or code editor, then change the text on line 18. +3. Save the changes in `app/views/todos.ejs`. +4. View your application at [https://localhost:3000](https://localhost:3000) to see the changes in real-time. + +## Step 6: Delete everything and start over + +Having your configuration stored in a Compose file has another advantage, you can easily delete everything and start over. + +To delete the application stack: + +1. Open the **Containers** tab of Docker Desktop +2. Select the Delete icon next to your application stack. + +![Deleting the application stack](images/getting-started-delete-stack.webp?w=300&border=true) + +After you delete the application stack, follow the steps from [Step 3: Run the +application](#step-3-run-the-application) to run the application again. Note +that when you delete the containers and run them again, any todos that you +created don't persist. + +## Summary + +In this walkthrough, you ran a multi-container application with Docker Compose. You also learned how to develop in containers and how to delete the application stack along with all of the data. + +Related information: + +- Deep dive into the [Docker Compose manual](../../compose/_index.md) +- Reference Compose commands in the [Docker Compose CLI reference](../../compose/reference/_index.md) +- Explore samples in the [Awesome Compose GitHub repository](https://github.com/docker/awesome-compose) +- Learn how to implement Compose Watch for your projects in [Use Compose Watch](../../compose/file-watch.md) + +## Next steps + +Continue to the next walkthrough to learn how to persist data even after deleting the application stack. + +{{< button url="./persist-data.md" text="Persist data between containers" >}} \ No newline at end of file diff --git a/content/guides/walkthroughs/persist-data.md b/content/guides/walkthroughs/persist-data.md new file mode 100644 index 00000000000..80cd1a5c91b --- /dev/null +++ b/content/guides/walkthroughs/persist-data.md @@ -0,0 +1,115 @@ +--- +title: Persist data between containers +keywords: get started, quick start, intro, concepts +description: Learn how to persist data between containers +--- + +This walkthrough shows you how to persist data between containers. To better understand some concepts in this walkthrough, complete the [Run multi-container applications](./multi-container-apps.md) walkthrough first. + +Docker isolates all content, code, and data in a container from your local filesystem. When you delete a container, Docker deletes all the content within that container. + +![Data isolation diagram](images/getting-started-isolation.webp?w=400) + +Sometimes, you may want to persist the data that a container generates. To do this, you can use volumes. + +Before you start, [get Docker Desktop](../../get-docker.md). + +## Step 1: Get the sample application + +If you have git, you can clone the repository for the sample application. Otherwise, you can download the sample application. Choose one of the following options. + +{{< tabs >}} +{{< tab name="Clone with git" >}} + +Use the following command in a terminal to clone the sample application repository. + +```console +$ git clone https://github.com/docker/multi-container-app +``` + +{{< /tab >}} +{{< tab name="Download" >}} + +Download the source and extract it. + +{{< button url="https://github.com/docker/multi-container-app/archive/refs/heads/main.zip" text="Download the source" >}} + +{{< /tab >}} +{{< /tabs >}} + +## Step 2: Add a volume to persist data + +To persist data after you delete a container, use a volume. A volume is a location in your local filesystem, automatically managed by Docker Desktop. + +![Volume diagram](images/getting-started-volume.webp?w=400) + +To add a volume to this project, open the `compose.yaml` file in a code or text editor, and then uncomment the following lines. + +```yaml +todo-database: + # ... + volumes: + - database:/data/db + +# ... +volumes: + database: +``` + +The `volumes` element that is nested under `todo-database` tells Compose to mount the volume named `database` to `/data/db` in the container for the todo-database service. + +The top-level `volumes` element defines and configures a volume named `database` that can be used by any of the services in the Compose file. + +## Step 3: Run the application + +To run the multi-container application, open a terminal and run the following commands. Replace `/path/to/multi-container-app/` with the path to your applications directory. + +{{< include "open-terminal.md" >}} + +```console +$ cd /path/to/multi-container-app/ +``` +```console +$ docker compose up -d +``` + +## Step 4: View the frontend and add todos + +In the **Containers** tab of Docker Desktop, you should now have an application stack with two containers running (the todo-app, and todo-database). + +To view the frontend and add todos: + +1. In Docker Desktop, expand the application stack in **Containers**. +2. Select the link to port **3000** in the **Port(s)** column or open [https://localhost:3000](https://localhost:3000)⁠. +3. Add some todo tasks in the frontend. + +## Step 5: Delete the application stack and run new containers + +Now, no matter how often you delete and recreate the containers, Docker Desktop persists your data and it's accessible to any container on your system by mounting the `database` volume. Docker Desktop looks for the `database` volume and creates it if it doesn't exist. + +To delete the application stack: + +1. Open the **Containers** tab of Docker Desktop +2. Select the Delete icon next to your application stack. + +![Deleting the application stack](images/getting-started-delete-stack.webp?w=300&border=true) + +After you delete the application stack, follow the steps from [Step 3: Run the +application](#step-3-run-the-application) to run the application again. Note +that when you delete the containers and run them again, Docker Desktop persists any todos that you created. + +## Summary + +In this walkthrough, you persisted data between containers using a volume. You can use this to persist and share data among isolated and ephemeral containers. + +Related information: + +- Deep dive into [volumes](../../storage/volumes.md) +- Learn about using volumes in Compose in the [Compose file reference](../../compose/compose-file/_index.md) +- Explore using volumes via the CLI in the [docker volume CLI reference](../../engine/reference/commandline/volume_create.md) and [Docker run reference](/reference/run/) + +## Next steps + +Continue to the next walkthrough to learn how you can access a local directory from a container. + +{{< button url="./access-local-folder.md" text="Access a local folder" >}} \ No newline at end of file diff --git a/content/guides/walkthroughs/publish-your-image.md b/content/guides/walkthroughs/publish-your-image.md new file mode 100644 index 00000000000..aa8f2870029 --- /dev/null +++ b/content/guides/walkthroughs/publish-your-image.md @@ -0,0 +1,70 @@ +--- +title: Publish your image +keywords: get started, quick start, intro, concepts +description: Learn how to publish your image to Docker Hub +aliases: +- /get-started/publish-your-own-image/ +--- + +Follow this walkthrough to learn how to publish and share your images on Docker Hub. + +Before you start, [get Docker Desktop](../../get-docker.md). + +## Step 1: Get the example image + +To get the example image: + +1. In Docker Desktop, select the search bar. +2. In the search bar, specify `docker/welcome-to-docker`. +3. Select **Pull** to pull the image from Docker Hub to you computer. + +![Search Docker Desktop for the welcome-to-docker image](images/getting-started-search.webp?w=400) + +## Step 2: Sign in to Docker + +Select **Sign in** on the top-right of Docker Desktop to either sign in or create a new Docker account. + +![Signing in to Docker Desktop](images/getting-started-signin.webp?w=300) + +## Step 3: Rename your image + +Before you can publish your image, you need to rename it so that Docker Hub knows that the image is yours. In a terminal, run the following command to rename your image. Replace `YOUR-USERNAME` with your Docker ID. + +{{< include "open-terminal.md" >}} + +```console +$ docker tag docker/welcome-to-docker YOUR-USERNAME/welcome-to-docker +``` + +## Step 4: Push your image to Docker Hub + +To push your image to Docker Hub: + +1. In Docker Desktop, go to the **Images** tab +2. In the **Actions** column for your image, select the **Show image actions** icon. +3. Select **Push to Hub**. + +![Pushing an image to Docker Hub](images/getting-started-push.webp?w=200&border=true) + +Go to [Docker Hub](https://hub.docker.com)⁠ and verify that the list of your repositories now contains `YOU-USERNAME/welcome-to-docker`. + +## Summary + +In this walkthrough, you pushed and shared an image on Docker Hub. + +Related information: + +- Deep dive into the [Docker Hub manual](../../docker-hub/_index.md) +- Learn more about the [docker tag](../../engine/reference/commandline/tag.md) + command + +## Next steps + +Continue to the language-specific guides to learn how you can use Docker to containerize and develop applications in your favorite language. Choose one of the following guides. + +- [C# (.NET)](../../language/dotnet/_index.md) +- [Go](../../language/golang/_index.md) +- [Java](../../language/java/_index.md) +- [Node.js](../../language/nodejs/_index.md) +- [Python](../../language/python/_index.md) +- [Rust](../../language/rust/_index.md) \ No newline at end of file diff --git a/content/guides/walkthroughs/run-a-container.md b/content/guides/walkthroughs/run-a-container.md new file mode 100644 index 00000000000..0f52d2607de --- /dev/null +++ b/content/guides/walkthroughs/run-a-container.md @@ -0,0 +1,89 @@ +--- +title: How do I run a container? +keywords: get started, quick start, intro, concepts +description: Learn how to build your own image and run it as a container +aliases: +- /get-started/run-your-own-container/ +--- + +In this walkthrough, you'll learn the basic steps of building an image and running your own container. This walkthrough uses a sample Node.js application, but it's not necessary to know Node.js. + +![Running an image in Docker Desktop](images/getting-started-run-intro.webp?w=400) + +Before you start, [get Docker Desktop](../../get-docker.md). + +## Step 1: Get the sample application + +If you have git, you can clone the repository for the sample application. Otherwise, you can download the sample application. Choose one of the following options. + +{{< tabs >}} +{{< tab name="Clone with git" >}} + +Use the following command in a terminal to clone the sample application repository. + +```console +$ git clone https://github.com/docker/welcome-to-docker +``` + +{{< /tab >}} +{{< tab name="Download" >}} + +Download the source and extract it. + +{{< button url="https://github.com/docker/welcome-to-docker/archive/refs/heads/main.zip" text="Download the source" >}} + +{{< /tab >}} +{{< /tabs >}} + +## Step 2: View the Dockerfile in your project folder + +To run your code in a container, the most fundamental thing you need is a +Dockerfile. A Dockerfile describes what goes into a container. This sample already contains a `Dockerfile`. For your own projects, you'll need to create your own `Dockerfile`. You can open the `Dockerfile` in a code or text editor and explore its contents. + +![Viewing Dockefile contents](images/getting-started-dockerfile.webp?w=400) + +## Step 3: Build your first image + +You always need an image to run a container. In a terminal, run the following commands to build the image. Replace `/path/to/welcome-to-docker/` with the path to your `welcome-to-docker` directory. + +{{< include "open-terminal.md" >}} + +```console +$ cd /path/to/welcome-to-docker/ +``` +```console +$ docker build -t welcome-to-docker . +``` + +Building the image may take some time. After your image is built, you can view your image in the **Images** tab in Docker Desktop. + +## Step 4: Run your container + +To run your image as a container: + +1. In Docker Desktop, go to the **Images** tab. +2. Next to your image, select **Run**. +3. Expand the **Optional settings**. +4. In **Host port**, specify `8089`. + ![Specifying host port 8089](images/getting-started-run-image.webp?w=250&border=true) +5. Select **Run**. + +## Step 5: View the frontend + +You can use Docker Desktop to access your running container. Select the link next to your container in Docker Desktop or go to [http://localhost:8089](http://localhost:8089) to view the frontend. + +![Selecting the container link](images/getting-started-frontend-2.webp?w=300&border=true) + +## Summary + +In this walkthrough, you built your own image and ran it as a container. In addition to building and running your own images, you can run images from Docker Hub. + +Related information: + +- Deep dive into building images in the [Build with Docker guide](../../build/guide/_index.md) + +## Next steps + +Continue to the next walkthrough to learn how you can run one of over 100,000 pre-made images from Docker Hub. + +{{< button url="./run-hub-images.md" text="Run Docker Hub images" >}} \ No newline at end of file diff --git a/content/guides/walkthroughs/run-hub-images.md b/content/guides/walkthroughs/run-hub-images.md new file mode 100644 index 00000000000..933ba498993 --- /dev/null +++ b/content/guides/walkthroughs/run-hub-images.md @@ -0,0 +1,63 @@ +--- +title: Run Docker Hub images +keywords: get started, quick start, intro, concepts +description: Learn how to run Docker Hub images +aliases: +- /get-started/run-docker-hub-images/ +--- + +You can share and store images in Docker Hub +([http://hub.docker.com](http://hub.docker.com)). Docker Hub 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. + +Before you start, [get Docker Desktop](../../get-docker.md). + +## Step 1: Search for the image + +You can search for Docker Hub images on Docker Desktop. To search for the image used in this walkthrough: + +1. Open Docker Desktop and select the search. +2. Specify `docker/welcome-to-docker` in the search. + +![Search Docker Desktop for the welcome-to-docker image](images/getting-started-search.webp?w=400) + +## Step 2: Run the image + +To run the `docker/welcome-to-docker` image: + +1. After finding the image using search, select **Run**. +2. Expand the **Optional settings**. +3. In **Host port**, specify `8090`. + ![Specifying host port 8090](images/getting-started-run.webp?w=250&border=true) +4. Select **Run**. + +> **Note** +> +> Many images hosted on Docker Hub have a description that highlights what +> settings must be set in order to run them. You can read the description for +> the image on Docker Hub by selecting the image name in the search or by +> searching for the image directly on +> [https://hub.docker.com](https://hub.docker.com). + +## Step 3: Explore the container + +That's it! The container is ready to use. Go to the **Containers** tab in Docker Desktop to view the container. + +![Viewing the Containers tab in Docker Desktop](images/getting-started-view.webp?w=400) + +## Summary + +In this walkthrough, you searched for an image on Docker Hub and ran it as a container. Docker Hub has over 100,000 more images that you can use to help build your own application. + +Related information: + +- Deep dive into the [Docker Hub manual](../../docker-hub/_index.md) +- Explore more images on [Docker Hub](https://hub.docker.com) + +## Next steps + +Continue to the next walkthrough to learn how you can use Docker to run +multi-container applications. + +{{< button url="./multi-container-apps.md" text="Run multi-container apps" >}} \ No newline at end of file diff --git a/content/guides/walkthroughs/what-is-a-container.md b/content/guides/walkthroughs/what-is-a-container.md new file mode 100644 index 00000000000..5920e1ea740 --- /dev/null +++ b/content/guides/walkthroughs/what-is-a-container.md @@ -0,0 +1,80 @@ +--- +title: What is a container? +keywords: get started, quick start, intro, concepts +description: Learn what a container is by seeing and inspecting a running container. +aliases: +- /get-started/what-is-a-container/ +--- + +A container is an isolated environment for your code. This means that a +container has no knowledge of your operating system, or your files. It runs on +the environment provided to you by Docker Desktop. Containers have everything +that your code needs in order to run, down to a base operating system. You can +use Docker Desktop to manage and explore your containers. + +In this walkthrough, you'll view and explore an actual container in Docker +Desktop. + +Before you start, [get Docker Desktop](../../get-docker.md). + +## Step 1: Set up the walkthrough + +The first thing you need is a running container. Use the following instructions to run a container. + +1. Open Docker Desktop and select the search. +2. Specify `docker/welcome-to-docker` in the search and then select **Run**. +3. Expand the **Optional settings**. +4. In **Container name**, specify `welcome-to-docker`. +5. In **Host port**, specify `8088`. + ![Specifying host port 8088](images/getting-started-setup.webp?w=250&border=true) +6. Select **Run**. + +## Step 2: View containers on Docker Desktop + +You just ran a container! You can view it in the **Containers** tab of Docker +Desktop. This container runs a simple 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. In this walkthrough, you only have a simple frontend container. + +![Docker Desktop with get-started container running](images/getting-started-container.webp?w=400) + +## Step 3: View the frontend + +The frontend is accessible on port 8088 of your local host. Select the link in +the **Port(s)** column of your container, or visit +[http://localhost:8088](http://localhost:8088) in your browser to view it. + +![Accessing container frontend from Docker Desktop](images/getting-started-frontend.webp?w=300&border=true) + +## Step 4: Explore your container + +Docker Desktop lets you easily view and interact with different aspects of your +container. Try it out yourself. Select your container and then select **Files** +to explore your container's isolated file system. + +![Viewing container details in Docker Desktop](images/getting-started-explore-container.webp?w=300&border=true) + +## Step 5: Stop your container + +The `welcome-to-docker` container continues to run until you stop it. To stop +the container in Docker Desktop, go to the **Containers** tab and select the +**Stop** icon in the **Actions** column of your container. + +![Stopping a container in Docker Desktop](images/getting-started-stop.webp?w=400) + +## Summary + +In this walkthrough, you ran a pre-made image and explored a container. In addition to running pre-made images, you can build and run your own application as container. + +Related information: + +- Read more about containers in [Use containers to Build, Share and Run your applications](https://www.docker.com/resources/what-container/) +- Deep dive in Liz Rice's [Containers from Scratch](https://www.youtube.com/watch?v=8fi7uSYlOdc&t=1s) video presentation + +## Next steps + +Continue to the next walkthrough to learn what you need to create your own image +and run it as container. + +{{< button url="./run-a-container.md" text="How do I run a container?" >}} \ No newline at end of file diff --git a/content/includes/open-terminal.md b/content/includes/open-terminal.md new file mode 100644 index 00000000000..81e5c365691 --- /dev/null +++ b/content/includes/open-terminal.md @@ -0,0 +1,11 @@ +> **Tip** +> +> To run Docker commands, you must use a terminal. Based on your +> operating system, you can open a terminal by doing the following: +> +> For Windows, select the Start Menu, specify `cmd`, and then select +> **Command Prompt**. +> +> For Mac, select the **Launchpad** icon in the Dock, specify `Terminal` in the +> search field, then select **Terminal**. +{ .tip } \ No newline at end of file diff --git a/data/toc.yaml b/data/toc.yaml index 8a660199db3..05843adad0a 100644 --- a/data/toc.yaml +++ b/data/toc.yaml @@ -25,6 +25,28 @@ Guides: path: /get-started/09_image_best/ - title: "Part 10: What next?" path: /get-started/11_what_next/ + +- sectiontitle: Walkthroughs + section: + - title: "Overview" + path: /guides/walkthroughs/ + - title: "What is a container?" + path: /guides/walkthroughs/what-is-a-container/ + - title: "How do I run a container?" + path: /guides/walkthroughs/run-a-container/ + - title: "Run Docker Hub images" + path: /guides/walkthroughs/run-hub-images/ + - title: "Run multi-container applications" + path: /guides/walkthroughs/multi-container-apps/ + - title: "Persist data between containers" + path: /guides/walkthroughs/persist-data/ + - title: "Access a local folder" + path: /guides/walkthroughs/access-local-folder/ + - title: "Containerize your application" + path: /guides/walkthroughs/containerize-your-app/ + - title: "Publish your image" + path: /guides/walkthroughs/publish-your-image/ + - sectiontitle: Language-specific guides section: - path: /language/