From b9ec34979bd24ca892d8329a8a0dfc2ccc4cda19 Mon Sep 17 00:00:00 2001 From: Joblin John Jeya Rockas Date: Mon, 27 Apr 2026 22:34:15 +0000 Subject: [PATCH] Update README.md --- README.md | 248 ++++++++++++++++++++++++------------------------------ 1 file changed, 111 insertions(+), 137 deletions(-) diff --git a/README.md b/README.md index baf1291..3a46f57 100644 --- a/README.md +++ b/README.md @@ -1,192 +1,166 @@ -# Docker Multi-Service Notes Application +# Notes Application - Docker & Kubernetes Deployment -## 1. Introduction +## Overview -This project is a multi-container web application deployed using Docker. -It demonstrates how multiple services such as frontend, backend, -database, and file storage can be containerized and orchestrated using -Docker Compose. +This project is a Notes Application deployed using Docker and Kubernetes (MicroK8s). +The application allows users to: -The system follows a microservices architecture where each service runs -independently and communicates through a Docker network. +- Create notes +- Delete notes +- Upload files +- Download files ------------------------------------------------------------------------- +It follows a 3-tier architecture: -## 2. Objectives +- Frontend (Nginx) +- Backend (Node.js) +- Database (MongoDB) -- Deploy a complete web application using Docker containers -- Use multiple services (frontend, backend, database) -- Enable communication between services -- Implement persistent storage using Docker volumes -- Provide scripts for managing the application lifecycle +## Architecture ------------------------------------------------------------------------- +``` +User -> Frontend (Nginx) -> Backend (Node.js) -> MongoDB +``` -## 3. System Architecture +## Containers -The application consists of the following services: +### Frontend -### 3.1 Frontend (Nginx) +- Image: `nginx:alpine` +- Role: Serves static UI +- Port: `80` -- Serves static files (HTML, CSS, JavaScript) -- Provides user interface for interacting with the system +### Backend -### 3.2 Backend (Node.js + Express) +- Image: `node:18` +- Role: API server (handles notes & files) +- Port: `3000` -- Handles API requests -- Implements business logic -- Manages notes and file uploads +### Database -### 3.3 MongoDB +- Image: `mongo:6.0` +- Role: Stores notes and file data +- Port: `27017` -- NoSQL database for storing notes -- Uses persistent storage +## Kubernetes Resources -### 3.4 Mongo Express +- Namespace: `z2` +- Deployments: + - `frontend` + - `backend` +- StatefulSet: + - `mongo` +- Services: + - `frontend` (NodePort -> 30007) + - `backend` (ClusterIP) + - `mongo` (Headless Service) -- Web interface to view and manage database data +## Storage ------------------------------------------------------------------------- +- Persistent Volume Claim: `mongo-storage` +- Size: `1Gi` +- Mount path: `/data/db` +- Purpose: Store MongoDB data persistently -## 4. Features +## Setup Instructions -- Create notes -- Delete notes -- Upload files -- List uploaded files -- Download files -- Persistent data storage +### 1. Prepare Application ------------------------------------------------------------------------- +```bash +./prepare-app.sh +``` -## 5. Technologies Used +- Builds Docker images +- Loads them into MicroK8s -- Docker -- Docker Compose -- Node.js (Express) -- MongoDB -- Nginx -- HTML, CSS, JavaScript +### 2. Start Application ------------------------------------------------------------------------- +```bash +./start-app.sh +``` -## 6. Ports and Services +- Deploys Kubernetes resources +- Starts all services -| Service | Port | Description | -|----------------|------|-----------------| -| Frontend | 8080 | Web interface | -| Backend | 3000 | API server | -| Mongo Express | 8081 | Database UI | +### 3. Stop Application ------------------------------------------------------------------------- -## 7. Database Credentials +```bash +./stop-app.sh +``` -The MongoDB database is configured with the following credentials: +- Stops running pods +- Keeps configuration -- **Username:** admin -- **Password:** pass +### 4. Delete Application -These credentials are used by Mongo Express to connect to the MongoDB service. +```bash +microk8s kubectl delete all --all -n z2 +microk8s kubectl delete pvc --all -n z2 +``` ------------------------------------------------------------------------- +- Removes everything including database -## 8. Persistent Storage +## Access Application -The application uses Docker volumes: +Open in browser: -- mongo-data → stores database data -- uploads → stores uploaded files +``` +http://:30007 +``` -These ensure that data is not lost when containers restart. +Example: ------------------------------------------------------------------------- +``` +http://147.232.204.210:30007 +``` -## 9. Network Requirement (IMPORTANT) +## Useful Commands -⚠️ This application is hosted on a university virtual machine. +Check pods: -To access the application, you must: +```bash +microk8s kubectl get pods -n z2 +``` -- Be connected to the **Tuke university network**, OR -- Use a **Tuke VPN connection** +Check services: -Without VPN/network access, the application URLs may not be reachable. +```bash +microk8s kubectl get svc -n z2 +``` ------------------------------------------------------------------------- +View logs: -## 10. Application Workflow +```bash +microk8s kubectl logs -n z2 +``` -1. User accesses frontend via browser -2. Frontend sends requests to backend API -3. Backend processes requests -4. Backend interacts with MongoDB -5. MongoDB stores/retrieves data -6. Mongo Express allows database visualization +## Common Issues ------------------------------------------------------------------------- +### Mongo Crash (version error) -## 11. Scripts +Fix: -### 11.1 Prepare Application +```bash +microk8s kubectl delete pvc --all -n z2 +``` - ./prepare-app.sh +### Frontend shows "Welcome to nginx" -- Builds Docker images -- Creates volumes and network +Fix: -### 11.2 Start Application +- Ensure `index.html` is copied in Dockerfile +- Rebuild using: - ./start-app.sh +```bash +./prepare-app.sh +``` -- Starts all containers -- Application available at: - - http://147.232.204.210:8080 - - http://147.232.204.210:8081 - - http://147.232.204.210:3000 - - http://147.232.204.210:3000/notes - +## Honesty Statement -### 11.3 Stop Application - - ./stop-app.sh - -- Stops all containers -- Data remains intact - -### 11.4 Remove Application - - ./remove-app.sh - -- Removes containers, volumes, and images - ------------------------------------------------------------------------- - -## 12. Docker Configuration - -The application is configured using docker-compose.yml, where: - -- Each service runs in its own container -- Services communicate using Docker networking -- Volumes are used for persistent storage - ------------------------------------------------------------------------- - -## 13. Key Concepts Demonstrated - -- Multi-container Docker architecture -- Service isolation and communication -- Persistent storage using volumes -- RESTful API design -- Static file serving - ------------------------------------------------------------------------- - -## 14. Conclusion - -This project demonstrates how to deploy a scalable web application using -Docker containers. It highlights the importance of modular architecture, -persistent storage, and service communication. - ------------------------------------------------------------------------- +This project was developed with the assistance of AI tools (such as ChatGPT) for: +- Debugging errors +- Understanding Kubernetes concepts +- Identifying fixes for deployment issues +All configurations, testing, and final implementation were completed independently, and the AI was used strictly as a learning aid. \ No newline at end of file