From ee41406114043be4b614587f66a5bfdd5f348de0 Mon Sep 17 00:00:00 2001 From: Craig Osterhout <103533812+craig-osterhout@users.noreply.github.com> Date: Mon, 11 Nov 2024 09:15:50 -0800 Subject: [PATCH] hub: refresh quickstart (#21374) ## Description Refreshed Hub Quickstart. - Added a brief intro. - Added the "how to find an image" use-case. - Updated pull/push steps to use the same image to show how easy it is to extend images. - Moved install DD and create an account as prereqs to keeps the steps Hub-focused. - Updated next steps to have a more natural flow related to the previous step. -------- Signed-off-by: Craig --- content/manuals/docker-hub/quickstart.md | 275 ++++++++++++++--------- 1 file changed, 174 insertions(+), 101 deletions(-) diff --git a/content/manuals/docker-hub/quickstart.md b/content/manuals/docker-hub/quickstart.md index 6930b9836ee..cd1708bed19 100644 --- a/content/manuals/docker-hub/quickstart.md +++ b/content/manuals/docker-hub/quickstart.md @@ -1,148 +1,221 @@ --- description: Learn how to get started using Docker Hub -keywords: Docker, docker, registry, accounts, plans, Dockerfile, Docker Hub, accounts, - organizations, repositories, groups, teams +keywords: Docker Hub, push image, pull image, repositories title: Docker Hub quickstart linkTitle: Quickstart weight: 10 --- -The following section contains step-by-step instructions on how to get started with Docker Hub. +Docker Hub provides a vast library of pre-built images and resources, +accelerating development workflows and reducing setup time. You can build upon +pre-built images from Docker Hub and then use repositories to share and +distribute your own images with your team or millions of other developers. -### Step 1: Sign up for a free Docker account +This guide shows you how to find and run a pre-built image. It then walks you +through creating a custom image and sharing it through Docker Hub. -Start by creating a [Docker ID](https://hub.docker.com/signup). +## Prerequisites -A [Docker ID](/accounts/create-account/) grants you access to Docker Hub repositories and lets you explore available images from the community and verified publishers. You also need a Docker ID to share images on Docker Hub. +- [Download and install Docker](../../get-started/get-docker.md) +- [Create a Docker account](https://app.docker.com/signup) -> [!TIP] -> -> Explore [Docker's core subscriptions](https://www.docker.com/pricing/) to see what else Docker can offer you. +## Step 1: Find an image in Docker Hub's library -### Step 2: Create your first repository +You can search for content in Docker Hub itself, in the Docker Desktop +Dashboard, or by using the `docker search` CLI command. Searching on Docker Hub +itself offers the most options to explore content. -To create a repository: +To search or browse for content on Docker Hub: -1. Sign in to [Docker Hub](https://hub.docker.com). -2. On the Repositories page, select **Create repository**. -3. Name it **<your-username>/my-private-repo**. -4. Set the visibility to **Private**. -5. Select **Create**. +1. Navigate to the [Docker Hub Explore page](https://hub.docker.com/explore). -You've created your first repository. + On the Explore page, you can browse by catalog or category, or use the search + to quickly find content. -### Step 3: Download and install Docker Desktop +2. Under **Categories**, select **Web servers**. -You need to download Docker Desktop to build, push, and pull container images. + After the results are displayed, you can further filter the results using the + filters on the left side of the page. -1. Download and install [Docker Desktop](/manuals/desktop/_index.md). +3. In the filters, select **Docker Official Image**. -2. Sign in to Docker Desktop using the Docker ID you created in step one. + Filtering by Trusted Content ensures that you see only high-quality, secure + images curated by Docker and verified publishing partners. -### Step 4: Pull and run a container image from Docker Hub +4. In the results, select the **nginx** image. -1. In your terminal, run `docker pull hello-world` to pull the image from Docker Hub. You should see output similar to: + Selecting the image opens the image's page where you can learn more about how + to use the image. On the page, you'll also find the `docker pull` command to + pull the image. + +Now that you've found an image, it's time to pull and run it on your device. + +## Step 2: Pull and run an image from Docker Hub + +1. In your terminal, run the following command to pull and run the Nginx image. ```console - $ docker pull hello-world - Using default tag: latest - latest: Pulling from library/hello-world - 2db29710123e: Pull complete - Digest: sha256:7d246653d0511db2a6b2e0436cfd0e52ac8c066000264b3ce63331ac66dca625 - Status: Downloaded newer image for hello-world:latest - docker.io/library/hello-world:latest + $ docker run -p 8080:80 --rm nginx ``` -2. Run `docker run hello-world` to run the image locally. You should see output similar to: - - ```console - $ docker run hello-world - Hello from Docker! - This message shows that your installation appears to be working correctly. + The `docker run` command automatically pulls and runs the image without the + need to run `docker pull` first. To learn more about the command and its + options, see the [`docker run` CLI + reference](../../reference/cli/docker/container/run.md). After running the + command, you should see output similar to the following. + + ```console {collapse=true} + Unable to find image 'nginx:latest' locally + latest: Pulling from library/nginx + a480a496ba95: Pull complete + f3ace1b8ce45: Pull complete + 11d6fdd0e8a7: Pull complete + f1091da6fd5c: Pull complete + 40eea07b53d8: Pull complete + 6476794e50f4: Pull complete + 70850b3ec6b2: Pull complete + Digest: sha256:28402db69fec7c17e179ea87882667f1e054391138f77ffaf0c3eb388efc3ffb + Status: Downloaded newer image for nginx:latest + /docker-entrypoint.sh: /docker-entrypoint.d/ is not empty, will attempt to perform configuration + /docker-entrypoint.sh: Looking for shell scripts in /docker-entrypoint.d/ + /docker-entrypoint.sh: Launching /docker-entrypoint.d/10-listen-on-ipv6-by-default.sh + 10-listen-on-ipv6-by-default.sh: info: Getting the checksum of /etc/nginx/conf.d/default.conf + 10-listen-on-ipv6-by-default.sh: info: Enabled listen on IPv6 in /etc/nginx/conf.d/default.conf + /docker-entrypoint.sh: Sourcing /docker-entrypoint.d/15-local-resolvers.envsh + /docker-entrypoint.sh: Launching /docker-entrypoint.d/20-envsubst-on-templates.sh + /docker-entrypoint.sh: Launching /docker-entrypoint.d/30-tune-worker-processes.sh + /docker-entrypoint.sh: Configuration complete; ready for start up + 2024/11/07 21:43:41 [notice] 1#1: using the "epoll" event method + 2024/11/07 21:43:41 [notice] 1#1: nginx/1.27.2 + 2024/11/07 21:43:41 [notice] 1#1: built by gcc 12.2.0 (Debian 12.2.0-14) + 2024/11/07 21:43:41 [notice] 1#1: OS: Linux 6.10.11-linuxkit + 2024/11/07 21:43:41 [notice] 1#1: getrlimit(RLIMIT_NOFILE): 1048576:1048576 + 2024/11/07 21:43:41 [notice] 1#1: start worker processes + 2024/11/07 21:43:41 [notice] 1#1: start worker process 29 + ... + ``` - To generate this message, Docker took the following steps: - 1. The Docker client contacted the Docker daemon. - 2. The Docker daemon pulled the "hello-world" image from the Docker Hub. - (amd64) - 3. The Docker daemon created a new container from that image which runs the - executable that produces the output you are currently reading. - 4. The Docker daemon streamed that output to the Docker client, which sent - it to your terminal. +2. Visit [https://localhost:8080](https://localhost:8080) to view the default + Nginx page and verify that the container is running. - To try something more ambitious, you can run an Ubuntu container with: - $ docker run -it ubuntu bash +3. In the terminal, press CTRL+C to stop the container. - Share images, automate workflows, and more with a free Docker ID: - https://hub.docker.com/ +You've now run a web server without any set up or configuration, all from a +single command. Docker Hub provides instant access to pre-built, ready-to-use +container images, letting you quickly pull and run applications without needing +to install or configure software manually. With Docker Hub's vast library of +images, you can experiment with and deploy applications effortlessly, boosting +productivity and making it easy to try out new tools, set up development +environments, or build on top of existing software. - For more examples and ideas, visit: - https://docs.docker.com/get-started/ - ``` +You can also extend images from Docker Hub, letting you quickly build and +customize your own images to suit specific needs. -### Step 5: Build and push a container image to Docker Hub from your computer +## Step 3: Build and push an image to Docker Hub -1. Start by creating a [Dockerfile](/reference/dockerfile.md) to specify your application as shown below: +1. Create a [Dockerfile](/reference/dockerfile.md) to specify your application: ```dockerfile - # syntax=docker/dockerfile:1 - FROM busybox - CMD echo "Hello world! This is my first Docker image." + FROM nginx + RUN echo "

Hello world from Docker!

" > /usr/share/nginx/html/index.html + ``` + + This Dockerfile extends the Nginx image from Docker Hub to create a + simple website. With just a few lines, you can easily set up, customize, and + share a static website using Docker. + +2. Run the following command to build your image. Replace `` with your Docker ID. + + ```console + $ docker build -t /nginx-custom . + ``` + + This command builds your image and tags it so that Docker understands which + repository to push it to in Docker Hub. To learn more about the command and + its options, see the [`docker build` CLI + reference](../../reference/cli/docker/buildx/build.md). After running the + command, you should see output similar to the following. + + ```console {collapse=true} + [+] Building 0.6s (6/6) FINISHED docker:desktop-linux + => [internal] load build definition from Dockerfile 0.0s + => => transferring dockerfile: 128B 0.0s + => [internal] load metadata for docker.io/library/nginx:latest 0.0s + => [internal] load .dockerignore 0.0s + => => transferring context: 2B 0.0s + => [1/2] FROM docker.io/library/nginx:latest 0.1s + => [2/2] RUN echo "

Hello world from Docker!

" > /usr/share/ 0.2s + => exporting to image 0.1s + => => exporting layers 0.0s + => => writing image sha256:f85ab68f4987847713e87a95c39009a5c9f4ad78 0.0s + => => naming to docker.io/mobyismyname/nginx-custom 0.0s + ``` + +3. Run the following command to test your image. Replace `` with + your Docker ID. + + ```console + $ docker run -p 8080:80 --rm /nginx-custom ``` -2. Run `docker build -t /my-private-repo .` to build your Docker - image. +4. Visit [https://localhost:8080](https://localhost:8080) to view the page. You + should see `Hello world from Docker!`. + +5. In the terminal, press CTRL+C to stop the container. -3. Run `docker run /my-private-repo` to test your -Docker image locally. +6. Sign in to Docker Desktop. You must be signed in before pushing an image to + Docker Hub. -4. Run `docker push /my-private-repo` to push your Docker image to Docker Hub. You should see output similar to: +7. Run the following command to push your image to Docker Hub. Replace `` with your Docker ID. ```console - $ cat > Dockerfile < [internal] load build definition from Dockerfile - => => transferring dockerfile: 110B - => [internal] load .dockerignore - => => transferring context: 2B - => [internal] load metadata for docker.io/library/busybox:latest - => CACHED [1/1] FROM docker.io/library/busybox@sha256:a9286defaba7n3a519 - => exporting to image - => => exporting layers - => => writing image sha256:dcdb1fd928bf257bfc0122ea47accd911a3a386ce618 - => => naming to docker.io/mobythewhale/my-private-repo - $ docker run mobythewhale/my-private-repo - Hello world! This is my first Docker image. - $ docker push mobythewhale/my-private-repo - The push refers to repository [docker.io/mobythewhale/my-private-repo] - d2421964bad1: Layer already exists - latest: digest: sha256:7604fbf8eeb03d866fd005fa95cdbb802274bf9fa51f7dafba6658294 - efa9baa size: 526 + $ docker push /nginx-custom ``` - >**Note** - > - > You must be signed in to Docker Hub through Docker Desktop or the command line, and you must also name your images correctly, as per the above steps. + The command pushes the image to Docker Hub and automatically + creates the repository if it doesn't exist. To learn more about the command, + see the [`docker push` CLI + reference](../../reference/cli/docker/image/push.md). After running the + command, you should see output similar to the following. + + ```console {collapse=true} + Using default tag: latest + The push refers to repository [docker.io/mobyismyname/nginx-custom] + d0e011850342: Pushed + e4e9e9ad93c2: Mounted from library/nginx + 6ac729401225: Mounted from library/nginx + 8ce189049cb5: Mounted from library/nginx + 296af1bd2844: Mounted from library/nginx + 63d7ce983cd5: Mounted from library/nginx + b33db0c3c3a8: Mounted from library/nginx + 98b5f35ea9d3: Mounted from library/nginx + latest: digest: sha256:7f5223ae866e725a7f86b856c30edd3b86f60d76694df81d90b08918d8de1e3f size: 1985 + ``` + + Now that you've created a repository and pushed your image, it's time to view + your repository and explore its options. + +## Step 4: View your repository on Docker Hub and explore options + +1. Go to [Docker Hub](https://hub.docker.com) and sign in. -5. Your repository in Docker Hub should now display a new `latest` tag under **Tags**: + After signing in, you should be on the **Repositories** page. If not, then go + to the [**Repositories**](https://hub.docker.com/repositories/) page. - ![Tag created](images/index-tag.webp) +2. Find the **nginx-custom** repository and select that row. -You've successfully: + After selecting the repository, you should see more details and options for + your repository. -- Signed up for a Docker account -- Created your first repository -- Pulled an existing container image from Docker Hub -- Built your own container image on your computer -- Pushed it successfully to Docker Hub +You've now verified that your repository exists on Docker Hub, and you've +discovered more options for it. View the next steps to learn more about some of +these options. -### Next steps +## Next steps -- Create an [organization](orgs.md) to use Docker Hub with your team. -- Automatically build container images from code through [builds](builds/_index.md). -- [Explore](https://hub.docker.com/explore) official & publisher images. -- [Upgrade your subscription](https://www.docker.com/pricing) to push additional private Docker images to -Docker Hub. +- Automatically build container images from code through + [builds](builds/_index.md). +- Use [webhooks](./webhooks.md) to cause an action in another service in + response to a push event in the repository. +- Manage [repository settings](./repos/_index.md) to set the default privacy for + your repositories. \ No newline at end of file