Docker: Publishing Images to Docker Hub - A Comprehensive Guide

Table of Contents#

1. Prerequisites
2. Setting Up a Docker Hub Account
3. Preparing Your Docker Image
4. Tagging Images for Docker Hub
5. Logging In to Docker Hub via CLI
6. Pushing Images to Docker Hub
7. Verifying the Pushed Image
8. Common Practices & Best Practices
9. Troubleshooting Common Issues
10. Conclusion
11. References

Prerequisites#

Before getting started, ensure you have the following:

• Docker Engine Installed: Docker Hub interacts with your local Docker setup. Install Docker Desktop (for Windows/macOS) or Docker Engine (for Linux) from the official Docker docs.
  Verify installation with:

  docker --version          # Check Docker version
  docker info               # Verify Docker is running

• Docker Hub Account: Sign up for a free account at hub.docker.com. Choose a unique username (e.g., johndoe)—this will be critical for tagging images later.

• A Docker Image to Publish: You’ll need a local Docker image (e.g., a custom app, tool, or modified base image). If you don’t have one, we’ll create a simple example later.

Setting Up a Docker Hub Account#

1. Sign Up: Go to hub.docker.com and click "Sign Up." Enter your details (username, email, password).
2. Verify Email: Confirm your email to activate your account.
3. Optional: Create a Repository (Recommended): While Docker Hub auto-creates repositories when you push an image, pre-creating a repository lets you configure settings (e.g., public/private, descriptions) upfront:
   • Log in to Docker Hub.
   • Click "Create Repository" → Enter a name (e.g., node-app), add a description, and set visibility (public/private).

Preparing Your Docker Image#

To demonstrate, let’s create a simple Node.js app and package it into a Docker image. Skip this step if you already have an image to publish.

Step 1: Create the App Files#

Create a project directory and add these files:

package.json#

{
  "name": "docker-hub-demo",
  "version": "1.0.0",
  "dependencies": {
    "express": "^4.18.2"
  },
  "scripts": {
    "start": "node index.js"
  }
}

index.js#

const express = require('express');
const app = express();
const port = 3000;
 
app.get('/', (req, res) => {
  res.send('Hello from Docker Hub! 🐳');
});
 
app.listen(port, () => {
  console.log(`App running on http://localhost:${port}`);
});

Dockerfile#

# Use an official Node.js runtime as the base image
FROM node:18-alpine
 
# Set working directory
WORKDIR /app
 
# Copy package files and install dependencies
COPY package*.json ./
RUN npm install
 
# Copy app source
COPY . .
 
# Expose the port the app runs on
EXPOSE 3000
 
# Command to run the app
CMD ["npm", "start"]

Step 2: Build the Image#

Run this command in the project directory to build the image:

docker build -t my-node-app .

• -t my-node-app: Tags the image with the name my-node-app (local reference).
• .: Uses the current directory as the build context.

Verify the image exists locally:

docker images | grep my-node-app
# Output: my-node-app   latest    <image-id>   2 minutes ago   120MB

Tagging Images for Docker Hub#

Docker Hub uses a specific tagging format to identify where to push images. The required format is:

<docker-hub-username>/<repository-name>:<tag>

• <docker-hub-username>: Your Docker Hub username (e.g., johndoe).
• <repository-name>: The name of your Docker Hub repository (e.g., node-app).
• <tag>: A version or label (e.g., v1.0, latest, prod).

Why Tagging Matters:#

• Without the correct tag, Docker won’t know to push to your Docker Hub account.
• Tags help version images (e.g., v1.0, v1.1) and distinguish environments (e.g., dev, prod).

How to Tag:#

Use the docker tag command to create a tagged version of your local image:

docker tag my-node-app johndoe/node-app:v1.0

• my-node-app: Local image name.
• johndoe/node-app:v1.0: Docker Hub target (username/repo:tag).

Verify the new tag:

docker images | grep johndoe/node-app
# Output: johndoe/node-app   v1.0    <image-id>   5 minutes ago   120MB

Pro Tip: Add a "latest" Tag#

It’s common to tag the most recent stable version as latest for convenience:

docker tag johndoe/node-app:v1.0 johndoe/node-app:latest

Logging In to Docker Hub via CLI#

Before pushing, you must authenticate with Docker Hub using the CLI:

docker login

You’ll be prompted for your Docker Hub username and password.

Using Access Tokens (Recommended for Security)#

For CI/CD pipelines or automation, avoid using your password. Instead, create a personal access token (PAT) in Docker Hub:

1. Go to Docker Hub → Account Settings → Security → "New Access Token."
2. Name the token (e.g., "CI Pipeline") and set permissions (e.g., write for pushing images).
3. Copy the token (it’s only shown once!).

Log in with the token:

docker login -u johndoe -p <your-access-token>

Pushing Images to Docker Hub#

Once tagged and logged in, push the image to Docker Hub with:

docker push johndoe/node-app:v1.0

What Happens During Push?#

• Docker checks your authentication.
• It uploads image layers to Docker Hub. Only layers not already on Docker Hub are uploaded (thanks to Docker’s layer caching).
• Once complete, the image is available in your Docker Hub repository.

Push the latest tag too (if created):

docker push johndoe/node-app:latest

Verifying the Pushed Image#

Via Docker Hub Website:#

1. Log in to hub.docker.com.
2. Navigate to your repository (e.g., johndoe/node-app).
3. You’ll see the tags (v1.0, latest) and image details (size, pull command).

Via CLI:#

Pull the image to verify it was successfully pushed (from another machine or after deleting the local copy):

docker pull johndoe/node-app:v1.0
docker run -p 3000:3000 johndoe/node-app:v1.0
# Visit http://localhost:3000 to see the app!

Common Practices & Best Practices#

1. Versioning with Semantic Tags#

Use Semantic Versioning (e.g., v1.0.0, v1.1.0) to track breaking changes, features, and patches. Avoid relying solely on latest—it can cause unexpected updates.

2. Keep Images Small#

• Use multi-stage builds to reduce image size. Example:

  # Build stage
  FROM node:18 AS build
  WORKDIR /app
  COPY package*.json ./
  RUN npm install
  COPY . .
  RUN npm run build
   
  # Production stage (smaller base image)
  FROM node:18-alpine
  WORKDIR /app
  COPY --from=build /app/dist ./dist
  COPY --from=build /app/package*.json ./
  RUN npm install --production
  EXPOSE 3000
  CMD ["node", "dist/index.js"]

• Use official slim/alpine base images (e.g., node:18-alpine instead of node:18).

3. Scan for Vulnerabilities#

Docker Hub includes a built-in vulnerability scanner. Enable it in your repository settings to catch security issues in base images or dependencies. For advanced scanning, use tools like Trivy or Docker Scout.

4. Document Your Image#

Add a README.md to your Docker Hub repository explaining:

• How to use the image (e.g., docker run commands).
• Environment variables.
• Exposed ports.
• Known limitations.

5. Use Private Repositories for Sensitive Code#

Free Docker Hub accounts do not include private repositories; a paid plan is required for private storage. Private repos prevent unauthorized access to proprietary images.

Troubleshooting Common Issues#

"denied: requested access to the resource is denied"#

• Cause: Incorrect tag (missing username or wrong repository name).
• Fix: Ensure the tag is in the format <username>/<repo>:<tag>.

"no basic auth credentials"#

• Cause: Not logged in to Docker Hub.
• Fix: Run docker login and enter your credentials or access token.

"manifest unknown: manifest unknown"#

• Cause: The tag doesn’t exist locally or on Docker Hub.
• Fix: Verify the tag with docker images and re-tag if needed.

"push access denied for "#

• Cause: You don’t have permission to push to the repository (e.g., trying to push to an official repo like nginx).
• Fix: Use your own username in the tag (e.g., johndoe/nginx-custom:v1).

Conclusion#

Publishing images to Docker Hub is a critical skill for sharing and distributing containerized applications. By following the steps outlined—preparing your image, tagging correctly, authenticating, and pushing—you can seamlessly share your work with collaborators or the broader community.

Remember to adhere to best practices like semantic versioning, image optimization, and security scanning to ensure your images are reliable, secure, and easy to use. With Docker Hub, you unlock a powerful platform for container distribution, enabling smoother DevOps workflows and collaboration.

References#

• Docker Hub Official Documentation
• Docker CLI tag Command
• Docker CLI push Command
• Semantic Versioning
• Docker Multi-Stage Builds
• Docker Hub Security Scanning