From Local Dockerfile to Kubernetes Deployment: A Complete Step-by-Step Guide

Introduction

In modern cloud-native development, containerisation and orchestration are fundamental skills. This guide walks you through the entire lifecycle of a simple Python application — from building a Docker image locally, storing it in GitHub, pushing it to Docker Hub, and finally running it in a Kubernetes cluster from another virtual machine.

By the end of this tutorial, you will have a fully reproducible workflow that mirrors real-world DevOps practices.

Prerequisites

Before starting, ensure you have:

  • A GitHub account

  • A Docker Hub account

  • Access to a cloud provider (e.g., DigitalOcean)

  • Basic knowledge of Linux terminal commands

  • Installed locally:

    • Docker
    • Git
    • Python (optional but useful for testing)

Step 1 — Create a Simple Python Application

Create a project folder:

mkdir python-docker-app
cd python-docker-app

Create a file called app.py:

from http.server import BaseHTTPRequestHandler, HTTPServer

class SimpleHandler(BaseHTTPRequestHandler):
    def do_GET(self):
        self.send_response(200)
        self.end_headers()
        self.wfile.write(b"Hello from Dockerized Python app!")

if __name__ == "__main__":
    server = HTTPServer(("0.0.0.0", 8000), SimpleHandler)
    print("Server running on port 8000...")
    server.serve_forever()

Step 2 — Create the Dockerfile

Create a file named Dockerfile:

# Use official Python image
FROM python:3.11-slim

# Set working directory
WORKDIR /app

# Copy application files
COPY app.py .

# Expose port
EXPOSE 8000

# Run the application
CMD ["python", "app.py"]

Step 3 — Test Locally with Docker

Build the image:

docker build -t python-docker-app .

Run the container:

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

Test in browser:

http://localhost:8000

Step 4 — Initialise Git and Push to GitHub

Initialise repository:

git init
git add .
git commit -m "Initial commit - Python Docker app"

Create a repository on GitHub, then:

git remote add origin https://github.com/YOUR_USERNAME/python-docker-app.git
git branch -M main
git push -u origin main

Step 5 — Create a Cloud VM (DigitalOcean Example)

  • Create a Droplet (Ubuntu recommended)
  • Add your SSH key (recommended)
  • Note the public IP address

Connect via SSH:

ssh root@YOUR_VM_IP

Step 6 — Install Docker on the VM

apt update
apt install -y docker.io
systemctl start docker
systemctl enable docker

(Optional) Allow non-root usage:

usermod -aG docker $USER

Log out and back in.

Step 7 — Clone the Repository

git clone https://github.com/YOUR_USERNAME/python-docker-app.git
cd python-docker-app

Step 8 — Build the Docker Image on the VM

docker build -t python-docker-app .

Verify:

docker images

Step 9 — Login to Docker Hub

docker login

Enter your credentials.

Step 10 — Tag the Image

Replace yourdockerhubusername accordingly:

docker tag python-docker-app yourdockerhubusername/python-docker-app:latest

Step 11 — Push the Image to Docker Hub

docker push yourdockerhubusername/python-docker-app:latest

Confirm the image appears in Docker Hub.

Step 12 — Prepare Another VM (Kubernetes Client)

Create another VM or reuse an existing one.

Install:

apt update
apt install -y docker.io

Install kubectl:

apt install -y curl
curl -LO "https://dl.k8s.io/release/latest/bin/linux/amd64/kubectl"
install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

Step 13 — Configure Kubernetes Access

You need access to a Kubernetes cluster (e.g., DigitalOcean Kubernetes, Minikube, or K3s).

Verify access:

kubectl get nodes

Step 14 — Deploy the Image Using kubectl

Run the container:

kubectl run python-app \
  --image=yourdockerhubusername/python-docker-app:latest \
  --port=8000

Check the pod:

kubectl get pods

Step 15 — Expose the Application

kubectl expose pod python-app --type=NodePort --port=8000

Get service details:

kubectl get svc

Step 16 — Access the Application

Find the NodePort and access:

http://NODE_IP:NODE_PORT

Additional Best Practices (Often Missed)

1. Use a .dockerignore

.git
__pycache__
*.pyc

2. Use Version Tags (Avoid only latest)

docker tag python-docker-app yourdockerhubusername/python-docker-app:v1.0
docker push yourdockerhubusername/python-docker-app:v1.0

3. Add Health Checks (Optional)

Inside Dockerfile:

HEALTHCHECK CMD curl --fail http://localhost:8000 || exit 1

4. Use Kubernetes Deployment Instead of Pod

kubectl create deployment python-app \
  --image=yourdockerhubusername/python-docker-app:latest

5. Scale the Application

kubectl scale deployment python-app --replicas=3

6. Debugging

kubectl logs <pod-name>
kubectl describe pod <pod-name>

Conclusion

This guide demonstrated a full DevOps workflow:

  • Building a Python application
  • Containerising it with Docker
  • Versioning and storing code in GitHub
  • Distributing images via Docker Hub
  • Deploying workloads into Kubernetes

These steps form the backbone of modern cloud-native systems. While the example is intentionally simple, the same workflow scales to production-grade systems with CI/CD pipelines, monitoring, and automated deployments.

Mastering this process ensures you can confidently move applications from your local machine into scalable, distributed environments.