How to Build and Publish a Docker Image to Docker Hub

By
Admin
-
0
8



Image by Editor | ChatGPT

 

# Introduction

 
You probably know the struggle if you’ve tried running your app on a different machine, a teammate’s laptop, a test server, or the cloud. Something always breaks. Maybe a package isn’t installed, or the Python version is off, or the environment just isn’t quite right.

That’s where Docker makes life easier. With Docker, you can bundle your entire app code, dependencies, and environment into a neat little container that runs the same everywhere. You can publish that container to Docker Hub so anyone can pull it down and run it instantly.

In this guide, I will walk through how to:

  • Write a simple Python app
  • Build a Docker image for it
  • Test it locally
  • Push it to Docker Hub so it’s shareable

 

# Prerequisites

 
Before we cover Dockerizing your Python app, make sure you have the following set up:

  1. Python Installed: Make sure Python is installed on your machine (preferably Python 3.7+). You can check this by running: python --version or python3 --version
  2. Docker Installed and Running: You’ll need Docker installed and running on your machine. If you haven’t installed it yet, download it from Docker Desktop. After installing, confirm Docker is working: docker --version
  3. Docker Hub Account: To publish your image online, you’ll need a free Docker Hub account. Sign up here if you don’t already have one: Docker Hub.

 

# Step 1: Create a Simple Python App

 
Before we get into Docker, we need something to actually containerize. So let’s start with a very basic Python web app using Flask, a lightweight web framework.

This app will have a single route that says hello. For that, create a folder named docker-python-app, and inside it, create two files:

 

// 1. app.py

from flask import Flask
app = Flask(__name__)

@app.route("https://www.kdnuggets.com/")
def hello():
    return "Hello World!"

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=8000)

 

In this code:

  • We create a Flask app.
  • We define one route (/) that returns a friendly message.
  • We run the app on host “0.0.0.0” so Docker can expose it outside the container.
  • The port is set to 8000.

 

// 2. requirements.txt

Docker needs to know what Python packages your app requires, so let’s list them in a requirements.txt file:

 

# Step 2: Create a Dockerfile

 
Now that you’ve got a Python app, we need to teach Docker how to build and run it. That’s what the Dockerfile is for. It’s basically a recipe that tells Docker:

“Here’s what base image to use, here’s how to install dependencies, and here’s how to run the app.”

In your project folder (docker-python-app), create a file called Dockerfile (no file extension):

# 1. Start with a lightweight Python base image
FROM python:3.11-slim

# 2. Set the working directory in the container
WORKDIR /app

# 3. Copy the dependency file and install packages
COPY requirements.txt .
RUN pip install --upgrade pip && pip install --no-cache-dir -r requirements.txt

# 4. Copy the rest of your app code
COPY . .

# 5. Tell Docker which port the app will use
EXPOSE 8000

# 6. Define the command to run your app
CMD ["python", "app.py"]

 

This file basically:

  • Uses a small official Python image
  • Installs your app’s dependencies
  • Copies your code inside the container
  • Runs app.py when the container starts

This is all you need to containerize your app. Now let’s build it.

 

# Step 3: Build the Docker Image

 
In your terminal inside the project directory, run:

docker build -t your_dockerhub_username/docker-python-app .

 

Do not forget to replace your_dockerhub_username with your actual username. In this command:

  • docker build tells Docker to create an image
  • -t lets you tag (name) the image so it’s easy to reference later
  • . tells Docker to use the current directory (where your Dockerfile lives)

After a minute or so, Docker will package your app into an image. You will see something in your terminal as:

Output

 

# Step 4: Run and Test Your Image Locally

 
Let’s make sure it actually works before we publish it.

Run this command:

docker run -p 8000:8000 your_dockerhub_username/docker-python-app

 

This command tells Docker:

  • “Run the container”
  • Map port 8000 on your local machine to port 8000 inside the container (where Flask is running)

You will see something in your terminal as:

 
Output
 

Now open your browser and go to http://localhost:8000. You should see:

 

If you see that, your image works exactly as expected.

 

# Step 5: Push the Docker Image to Docker Hub

 
Now push your image to your Docker Hub repository using the command:

docker push your_dockerhub_username/docker-python-app

 

If prompted, authenticate first with docker login using your Docker Hub credentials.

 
Output

 

# Step 6: Pull and Run from Anywhere

 
Anyone can now pull your Docker image using:

docker pull image_owner_username/docker-python-app

 

The <image_owner_username> refers to the Docker Hub username of the person or organization who owns the image, not yours (unless you are the owner). For example, if your username is john123 and you want to pull this image, you would type:

docker pull kanwal5119/docker-python-app

 

Because kanwal5119 owns the image, you can only pull and run it, not modify or push to it unless you have access.

Run it using the command:

 

docker run -p 8000:8000 image_owner_username/docker-python-app

 

For your output, go to http://localhost:8000 or http://127.0.0.1:8000/

 
Output

 

# Conclusion

 
In this article, you learned how to create a Python app, containerize it using Docker, test it locally, and push it to Docker Hub, making it portable, shareable, and ready to run anywhere. This makes your development workflow cleaner and more scalable. If you want to go further, try:

  • Adding version tags like: v1.0 to your images.
  • Creating a .dockerignore file to optimize builds.
  • Setting up automated builds with GitHub + Docker Hub.
  • Running your image on a cloud platform (like AWS, GCP, or Azure).

There’s a lot more you can do with Docker, but now you’ve got the basics locked in. If you get stuck at any point or have any questions, leave a comment below.
 
 

Kanwal Mehreen is a machine learning engineer and a technical writer with a profound passion for data science and the intersection of AI with medicine. She co-authored the ebook “Maximizing Productivity with ChatGPT”. As a Google Generation Scholar 2022 for APAC, she champions diversity and academic excellence. She’s also recognized as a Teradata Diversity in Tech Scholar, Mitacs Globalink Research Scholar, and Harvard WeCode Scholar. Kanwal is an ardent advocate for change, having founded FEMCodes to empower women in STEM fields.