> ## Content Index
> Fetch the complete content index at: https://linuxhandbook.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# Build, Tag and Push Your Custom Docker Image to Repository
- URL: https://linuxhandbook.com/docker-push-repo/
- Published: 2025-03-28T11:48:28.000Z
- Updated: 2025-03-28T11:48:28.000Z
- Description: Learn how to create, tag, and push your custom Docker image to a repository in this step-by-step guide for efficient containerization workflows.
- Author: Abhishek Kumar
- Tags: Docker Tutorials

Docker has changed the way we package and distribute applications, but I only truly appreciated its power when I needed to share a project with a friend. 

Initially, we used `docker save` and `docker load` to transfer the image, which worked fine but was cumbersome. 

Then, while browsing the Docker documentation, I discovered how easy it was to push images to [Docker Hub](https://hub.docker.com/?ref=linuxhandbook.com). 

That was a game-changer! Now, I push my final builds to Docker Hub the moment they're done, allowing my clients and collaborators to pull and run them effortlessly.

In this guide, I’ll walk you through building, tagging, pushing, and running a Docker image. 

To keep things simple, we’ll create a minimal test image. 

💡

If you're new to Docker and want a deep dive, check out our DevOps course, which covers Docker extensively. We’ve covered Docker installation in countless tutorials as well, so we’ll skip that part here and jump straight into writing a Dockerfile.

## Writing a simple Dockerfile

A Dockerfile defines how to build your image. It contains a series of instructions that tell Docker how to construct the image layer by layer. 

Let’s create a minimal one:

```docker
# Use an official lightweight image
FROM alpine:latest

# Install a simple utility
RUN apk add --no-cache figlet

# Set the default command
CMD ["/usr/bin/figlet", "Docker is Fun!"]
```

- `FROM alpine:latest` – This sets the base image to Alpine Linux, a minimal and lightweight distribution.
- `RUN apk add --no-cache figlet` – Installs the `figlet` package using Alpine's package manager (`apk`), with the `--no-cache` option to keep the image clean.
- `CMD ["/usr/bin/figlet", "Docker is Fun!"]` – Specifies the default command that will run when a container is started.

Save this file as `Dockerfile` in an empty directory.

![creating dockerfile](https://linuxhandbook.com/content/images/2025/03/creating-dockerfile.png)

## Building the docker image

To build the image, navigate to the directory containing the Dockerfile and run:

```bash
docker build -t <cool-image-name> .
```

- `docker build` – The command to build an image.
- `-t cool-image-name` – The `-t` flag assigns a tag (`cool-image-name`) to the image, making it easier to reference later.
- `.` – The dot tells Docker to look for the `Dockerfile` in the current directory.

![building docker image](https://linuxhandbook.com/content/images/2025/03/docker-build.png)

Once completed, list your images to confirm:

```bash
docker images
```

![viewing installed docker images](https://linuxhandbook.com/content/images/2025/03/docker--images-notag.png)

## Running the docker image

To run the container and see the output:

```bash
docker run <cool-image-name>
```

You should see an ASCII text saying, “Docker is fun!”

![running the created docker image](https://linuxhandbook.com/content/images/2025/03/docker-run.png)

## Tagging the Image

Before pushing to a registry, we need to tag the image with our Docker Hub username:

```bash
docker tag <cool-image-name> your-dockerhub-username/cool-image-name:latest
```

- `docker tag` – Creates an alias for the image.
- `your-dockerhub-username/cool-image-name:latest` – This follows the format `username/repository-name:tag`. The `latest` tag is used as a default version identifier.

List images again to see the updated tag:

```bash
docker images
```

![tagging the created lhb-tutorial image with username followed by image name](https://linuxhandbook.com/content/images/2025/03/docker-images-2.png)

## Pushing to Docker Hub

First, log in to Docker Hub:

```bash
docker login
```

💡

If you’re using two-factor authentication, you’ll need to generate an access token from Docker Hub and use that instead of your password.

You will be prompted to enter your Docker Hub username and password. 

![logging in docker](https://linuxhandbook.com/content/images/2025/03/docker-login.png)

Once authenticated, you can push the image:

```bash
docker push your-dockerhub-username/cool-image-name:latest
```

![pushing image to docker hub](https://linuxhandbook.com/content/images/2025/03/docker-push.png)

And that’s it! Your image is now live on Docker Hub.

![docker hub repository for lhb-tutorial](https://linuxhandbook.com/content/images/2025/03/dockerhub.png)

 Anyone can pull and run it with:

```bash
docker pull your-dockerhub-username/cool-image-name:latest
docker run your-dockerhub-username/cool-image-name
```

Feels great, doesn’t it?

## Alternatives to Docker Hub

Docker Hub is not the only place to store images. Here are some alternatives:

- [**GitHub Container Registry (GHCR.io)**](https://github.com/features/actions?ref=linuxhandbook.com) – If you already use GitHub, this is a great option as it integrates with GitHub Actions and repositories seamlessly.
- [**Google Container Registry (GCR.io)**](https://cloud.google.com/artifact-registry/docs?ref=linuxhandbook.com) – Ideal for those using Google Cloud services. It allows private and public image hosting with tight integration into GCP workloads.
- [**Amazon Elastic Container Registry (ECR)**](https://aws.amazon.com/ecr/?ref=linuxhandbook.com) – Part of AWS, ECR is an excellent option for those using AWS infrastructure, providing strong security and IAM-based authentication.

#### Self-hosted Docker Registry

If you need complete control over your images, you can set up your own registry by running:

```
docker run -d -p 5000:5000 --name registry registry:2
```

This starts a private registry on port 5000, allowing you to store and retrieve images without relying on external providers.

You can read more about this in docker's official documentation to [host your own docker registry](https://www.docker.com/blog/how-to-use-your-own-registry-2/?ref=linuxhandbook.com).

## Final thoughts

Building and pushing Docker images has completely streamlined how I distribute my projects. 

What once felt like a tedious process is now as simple as writing a Dockerfile, tagging an image, and running a single push command. 

No more manual file transfers or complex setup steps, it’s all automated and ready to be pulled anywhere.

However, Docker Hub's free tier limits private repositories to just one. For personal projects, that’s a bit restrictive, which is why I’m more inclined toward self-hosting my own Docker registry. 

It gives me complete control, avoids limitations, and ensures I don’t have to worry about third-party policies.

What about you? Which container registry do you use for your projects? Have you considered self-hosting your own registry? Drop your thoughts in the comments.