Skip to content

Commit

Permalink
hub: refresh quickstart (#21374)
Browse files Browse the repository at this point in the history 
<!--Delete sections as needed -->

## 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 <[email protected]>
  • Loading branch information
@craig-osterhout
craig-osterhout authored Nov 11, 2024
1 parent d4c7e4a commit ee41406
Showing 1 changed file with 174 additions and 101 deletions.
275 changes: 174 additions & 101 deletions content/manuals/docker-hub/quickstart.md
View file
Original file line number Diff line number Diff line change
@@ -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 **&lt;your-username&gt;/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 "<h1>Hello world from Docker!</h1>" > /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 `<YOUR-USERNAME>` with your Docker ID.

```console
$ docker build -t <YOUR-USERNAME>/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 "<h1>Hello world from Docker!</h1>" > /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 `<YOUR-USERNAME>` with
your Docker ID.

```console
$ docker run -p 8080:80 --rm <YOUR-USERNAME>/nginx-custom
```

2. Run `docker build -t <your_username>/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 <your_username>/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 <your_username>/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 `<YOUR-USERNAME>` with your Docker ID.

```console
$ cat > Dockerfile <<EOF
FROM busybox
CMD echo "Hello world! This is my first Docker image."
EOF
$ docker build -t mobythewhale/my-private-repo .
[+] Building 1.2s (5/5) FINISHED
=> [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 <YOUR-USERNAME>/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.

0 comments on commit ee41406

Please sign in to comment.