diff --git a/z1/README.md b/z1/README.md index b3fc02b..b2ebb44 100644 --- a/z1/README.md +++ b/z1/README.md @@ -1,114 +1,135 @@ -# DOCKER APP DOCUMENTATION +# KUBERNETES APP DOCUMENTATION ## AUTHOR : Somangsu Mukherjee +--- + **1. Conditions for Deployment** The application requires the following software: -- Docker (version 20 or newer) -- Docker Compose (v2 or integrated with Docker) -- Bash shell (for .sh scripts) or PowerShell/CMD (Windows) -- Internet connection (to download Docker images) +- Docker (version 20 or newer) +- Kubernetes (Docker Desktop Kubernetes or Minikube) +- kubectl (configured and working) +- Bash shell (WSL recommended on Windows) +- Internet connection (to download container images) + +--- **2. Application Description** -This is a simple multi-container web application. +This is a Kubernetes-based multi-container web application. The application allows users to: -Enter their name in a web interface -Submit the name to a backend server -Store the name in a PostgreSQL database -Retrieve and display all stored names +- Enter their name in a web interface +- Submit the name to a backend server +- Store the name in a PostgreSQL database +- Retrieve and display all stored names -The application demonstrates communication between multiple services using Docker. +The application demonstrates communication and orchestration of multiple services using Kubernetes. + +--- **3. Virtual Networks and Volumes** -Virtual Network -Docker Compose automatically creates a virtual network for communication between services. +**Virtual Network** + +Kubernetes automatically manages networking between services and pods using internal DNS. Services communicate using service names: -Frontend communicates with backend (backend) -Backend communicates with database (db) -Named Volume -pgdata is used for persistent database storage -It is mounted to /var/lib/postgresql/data inside the PostgreSQL container -This ensures that data is preserved even if containers are stopped or restarted +- Backend communicates with database (`db`) +- External users access backend through NodePort service + +**Named Volume** + +Persistent storage is implemented using: + +- PersistentVolume (PV) +- PersistentVolumeClaim (PVC) + +These are mounted to `/var/lib/postgresql/data` inside the PostgreSQL container + +This ensures that data is preserved even if pods are restarted or recreated + +--- **4. Container Configuration** -Frontend -Image: nginx:latest -Port: 8080 (mapped to container port 80) -Volume: ./frontend mounted to /usr/share/nginx/html -Purpose: the frontend serves static HTML and JavaScript -Backend -Built from a custom Dockerfile (Node.js) -Port: 3000 -Uses Express framework and also communicates with PostgreSQL database to send entered names to be stored +**Backend** -Database (PostgreSQL) -Image: postgres:15 -Internal port: 5432 -Environment variables: -POSTGRES_USER=user -POSTGRES_PASSWORD=password -POSTGRES_DB=mydb -the database uses named volume pgdata for persistence which makes sure that data is not lost even after stopping or removing the container. -Uses init.sql for initial database setup +- Image: `docker-app-backend:latest` +- Port: `3000` +- Built using Node.js and Express framework +- Communicates with PostgreSQL database to store and retrieve names +- Deployed using Kubernetes Deployment -Adminer -Image: adminer -Port: 8081 -Purpose: Web interface for managing the PostgreSQL database which stores all the data that is entered +**Database (PostgreSQL)** -5. The table below describes all the containers utilised in this assignment -| Container | Description | -| --------- | -------------------------------------------- | -| frontend | Nginx web server serving the frontend | -| backend | Node.js server handling API requests | -| db | PostgreSQL database storing application data | -| adminer | Web interface for managing the database | +- Image: `postgres:15` +- Port: `5432` +- Environment variables: + - `POSTGRES_USER=user` + - `POSTGRES_PASSWORD=password` + - `POSTGRES_DB=mydb` +The database uses PersistentVolume and PersistentVolumeClaim for persistence which ensures that data is not lost even after pod restarts + +Uses StatefulSet for stable identity and storage + +--- + +**5. The table below describes all the components utilised in this assignment** + +| Component | Description | +|--------------|--------------------------------------------------| +| Namespace | Isolates all application resources | +| Deployment | Runs Node.js backend application | +| StatefulSet | Runs PostgreSQL database with persistent storage | +| Service | Exposes backend externally using NodePort | +| DB Service | Enables internal communication with database | + +--- **6. Application Control** -Prepare Application: -To prepare the application, the command ./prepare-app.sh is run in wsl which builds images and prepares the environment for execution. +**Prepare Application:** +To prepare the application, the backend image must be built using: -Start Application: -./start-app.sh is run in the wsl command line to start all the 4 cointainers in detached mode. +```bash +docker build -t docker-app-backend ./backend + +**Start Application:** +Run the following command in WSL: + +./start-app.sh + +This creates all Kubernetes resources and starts the application Stop Application -to stop all the currently running containers without deleting data, ./stop-app.sh is run on wsl +To stop the application: -Remove Application -./remove-app.sh stops all containers and removes volumes, networks, and all resources. +./stop-app.sh + +**Remove Application** +Deleting the namespace removes all resources completely: + +kubectl delete namespace myapp **7. Accessing the Application** -Main Web Application can be accessed on any browser locally running on http://localhost:8080 -The database Interface (Adminer) can be accessed similarly at http://localhost:8081 - -Login credentials for Adminer are: - -System: PostgreSQL -Server: db -Username: user -Password: password -Database: mydb +Backend API can be accessed at: +http://localhost:30007 +Frontend can be accessed by opening: +frontend/index.html **8. Used Resources** -Docker official documentation -Docker Compose documentation + +Kubernetes official documentation +Docker documentation Node.js documentation PostgreSQL documentation -Nginx documentation - -**9. Use of Artificial Intelligence** - -Artificial intelligence tools such as chatGPT and Claude were used as a support tool during development for understanding docker concepts and debugging scripts. Some configuration issues were also fixed by referring to AI. All implementation, testing, and integration were performed independently. +9. Use of Artificial Intelligence +Artificial intelligence tools were used as a support tool during development for understanding Kubernetes concepts and debugging deployment issues. Some configuration problems were resolved with AI assistance. All implementation, testing, and integration were performed independently. \ No newline at end of file