Skip to content
Blog

Pushing Images to Docker Hub and Private Registries

Step-by-step tutorial on tagging and pushing container images to Docker Hub, Harbor, AWS ECR, and self-hosted OCI registries.

Published on • November 18, 2026

AI Assistant

Building a container image locally is only the first step in software delivery. To make your application available to remote servers, Kubernetes clusters, or team members, you must publish (push) your built images to a central OCI container registry.

In this step-by-step tutorial, we will walk through tagging conventions, authenticating with registries, pushing images to Docker Hub and self-hosted private registries (like Harbor or AWS ECR), and troubleshooting common push errors.

The Image Push Workflow

+-----------------------+     1. docker build -t app:v1     +-----------------------+
| Local Docker Daemon   | --------------------------------> | Local Image Store     |
+-----------------------+                                   +-----------------------+
            |                                                           |
            | 2. docker tag app:v1 registry.com/team/app:v1             |
            v                                                           v
+-----------------------------------------------------------------------------------+
|  3. docker push registry.com/team/app:v1                                          |
|     - Uploads missing layer blobs in parallel                                     |
|     - Uploads manifest JSON                                                       |
+-----------------------------------------------------------------------------------+
            |
            v
+-----------------------------------------------------------------------------------+
| Remote Container Registry (Docker Hub / Harbor / ECR / Self-Hosted)               |
+-----------------------------------------------------------------------------------+

Step 1: Correct Image Tagging

The docker push command uses the image repository name to determine where to push the image. If your tag does not include a domain host prefix, Docker assumes the destination is Docker Hub (docker.io).

Tagging Syntax

docker tag <local-image>:<local-tag> <target-registry-domain>/<namespace>/<repository>:<tag>

Examples:

  • Docker Hub (User Account): docker tag my-web-app:latest johnsmith/web-app:v1.0.0
  • Docker Hub (Organization): docker tag my-web-app:latest acme-corp/web-app:v1.0.0
  • Self-Hosted Registry (Port 5000): docker tag my-web-app:latest registry.internal.net:5000/finance/web-app:v1.0.0
  • AWS Elastic Container Registry (ECR): docker tag my-web-app:latest 123456789012.dkr.ecr.us-east-1.amazonaws.com/finance/web-app:v1.0.0

Step 2: Authenticating with the Registry

Before pushing, you must establish an authenticated session using docker login.

Option A: Logging into Docker Hub

# Enter your Docker Hub username and Personal Access Token (PAT)
docker login

Option B: Logging into a Self-Hosted Private Registry

docker login registry.internal.net:5000 -u myuser -p mytoken

Option C: Logging into AWS ECR (via AWS CLI)

aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com

Step 3: Executing docker push

Once tagged and authenticated, push your image:

docker push registry.internal.net:5000/finance/web-app:v1.0.0

Sample Output:

The push refers to repository [registry.internal.net:5000/finance/web-app]
a29b4e710d22: Pushed 
f83b1928a410: Layer already exists 
c71982b54e11: Pushed 
v1.0.0: digest: sha256:7f8a91b2c3d4e5f6... size: 1572

Notice Layer already exists: Docker reuses layers already present in the remote registry, significantly saving bandwidth and upload time!

Pushing All Tags at Once

If you have assigned multiple tags to the same image (e.g., :v1.0.0, :v1.0, and :latest), you can push all tags associated with a repository name using --all-tags (or -a):

docker push --all-tags registry.internal.net:5000/finance/web-app

Troubleshooting Common Push Errors

1. denied: requested access to the resource is denied

  • Cause: You are not logged in, or your account lacks write/push permissions for the target repository.
  • Fix: Re-run docker login with a token that has push permissions.

2. http: server gave HTTP response to HTTPS client

  • Cause: You are attempting to push over unencrypted HTTP to a private registry, but Docker CLI requires TLS by default.
  • Fix: Configure TLS/HTTPS on your registry, or add the registry to your host’s insecure-registries list in /etc/docker/daemon.json (development only).

3. name unknown: repository name not found

  • Cause: The repository namespace has not been created yet on registries that require pre-creation (like ECR or Harbor).
  • Fix: Create the target project/repository in the registry console before pushing.

Summary Checklist

  1. Always tag your image with the explicit target registry domain and namespace.
  2. Authenticate securely using Personal Access Tokens or temporary cloud credentials (docker login).
  3. Leverage layer re-use by keeping base layers consistent across services.
  4. Verify the push completed by checking the returned SHA-256 digest.