From e02bb750cdb3fa121ad18843d2879ec3d88565f4 Mon Sep 17 00:00:00 2001
From: Hafzal Ahamed Hasan Mohamed
 <hafzal.ahamed.hasan.mohamed@student.tuke.sk>
Date: Wed, 16 Apr 2025 09:34:59 +0000
Subject: [PATCH] Update z2/README.md

---
 z2/README.md | 130 +++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 122 insertions(+), 8 deletions(-)

diff --git a/z2/README.md b/z2/README.md
index fb4ae95..9dbd140 100644
--- a/z2/README.md
+++ b/z2/README.md
@@ -1,15 +1,129 @@
-# Flask + PostgreSQL Kubernetes WebApp
+# 📘 Flask + PostgreSQL Kubernetes WebApp
+
+A lightweight full-stack web application powered by **Flask** and **PostgreSQL**, containerized with **Docker**, and deployed on **Kubernetes (Minikube)** using custom `Namespace`, `Deployment`, `StatefulSet`, and `Services`. Designed to demonstrate a production-like cloud-native architecture.
+
+---
 
 ## 📁 Project Structure
-- `app/`: Flask source code (`main.py`, `requirements.txt`)
-- `k8s/`: All Kubernetes manifests
-- `Dockerfile`: For building the Flask app image
 
-## 🛠️ Setup
-
-### Build the Flask Image
 ```bash
-./prepare-app.sh
+z2/
+├── app/
+│   ├── main.py                 # Flask application logic
+│   └── requirements.txt        # Python dependencies
+├── k8s/
+│   ├── namespace.yaml          # Custom namespace
+│   ├── deployment.yaml         # Flask app deployment
+│   ├── postgres-deployment.yaml  # PostgreSQL StatefulSet + PVC + Service
+│   ├── migrate-job.yaml        # Migration job (optional)
+│   ├── service.yaml            # Flask NodePort Service
+├── Dockerfile                  # For building Flask app image
+├── prepare-app.sh             # Script: Build & tag Docker image
+├── start-app.sh               # Script: Apply all Kubernetes configs
+├── stop-app.sh                # Script: Delete all resources
+└── README.md                   # Project documentation
+```
+
+---
+
+## 🚀 How It Works
+
+1. **Prepare the Environment**  
+   ```bash
+   ./prepare-app.sh
+   ```
+   - Builds and tags Docker image locally
+   - Prepares persistent volume (PVC) for PostgreSQL
+
+2. **Deploy the Application**  
+   ```bash
+   ./start-app.sh
+   ```
+   - Creates namespace, StatefulSet, Deployments, Services
+
+3. **Access the Web App**
+   ```bash
+   minikube service flask-service -n webapp-namespace
+   ```
+   - Opens the app in your browser (NodePort)
+
+4. **Stop and Clean Everything**
+   ```bash
+   ./stop-app.sh
+   ```
+   - Deletes all created Kubernetes resources
+
+---
+
+## 🪰 Technologies Used
+
+| Tool            | Purpose                      |
+|----------------|------------------------------|
+| Flask           | Web framework (Python)        |
+| PostgreSQL      | Relational database           |
+| Docker          | Containerization              |
+| Kubernetes      | Container orchestration       |
+| Minikube        | Local Kubernetes environment  |
+
+---
+
+## �ힺ Health Checks
+
+To ensure resilience and uptime, Kubernetes probes can be added:
+
+```yaml
+livenessProbe:
+  httpGet:
+    path: /health
+    port: 8000
+  initialDelaySeconds: 5
+  periodSeconds: 10
+
+readinessProbe:
+  httpGet:
+    path: /health
+    port: 8000
+  initialDelaySeconds: 5
+  periodSeconds: 10
+```
+
+👉 Add a `/health` route to your `main.py`:
+```python
+@app.route('/health')
+def health():
+    return "OK", 200
+```
+
+---
+
+## 🔍 Troubleshooting
+
+| Problem                             | Solution                                                                 |
+|-------------------------------------|--------------------------------------------------------------------------|
+| ❌ `ImagePullBackOff` or `ErrImagePull` | Make sure image is built locally with `docker build -t flask-app .` and you're using `imagePullPolicy: Never` |
+| ❌ App not accessible               | Check service type is `NodePort`, port 30080 is exposed, and run `minikube service flask-service -n webapp-namespace` |
+| ❌ Database errors                  | Ensure PostgreSQL pod is running (`kubectl get pods -n webapp-namespace`), check PVC and env vars |
+| ❌ "command not found: kubectl"    | Install `kubectl` and make sure it’s configured with `minikube` context |
+| ❌ Connection refused errors       | Check that `POSTGRES_HOST` matches the service name (`postgres`) and app waits until DB is ready |
+
+---
+
+## 🌱 Future Enhancements
+
+- Use Helm for templated deployments
+- Add database migrations (Alembic / Flask-Migrate)
+- CI/CD integration with GitLab or GitHub Actions
+- Add Redis or caching layer
+- Auto-scaling and HorizontalPodAutoscaler
+
+
+
+## 👨‍💻 Author
+
+**Hafzal Ahamed Hasan Mohamed**  
+TUKE, Faculty of Electrical Engineering and Informatics  
+Git: [git.kemt.fei.tuke.sk/hh304ug/zkt25](https://git.kemt.fei.tuke.sk/hh304ug/zkt25)
+
 
 hafzal03@LAPTOP-ELUS3HGM:~/mypro/z2$ kubectl get pods -n webapp-namespace
 NAME                        READY   STATUS    RESTARTS   AGE