From 8171d3b1978d3f99f7991f4ec360efa504a5b36f Mon Sep 17 00:00:00 2001 From: Charles Mendiburu Date: Wed, 29 Apr 2026 01:10:19 +0200 Subject: [PATCH] Add of the README.md : explain config about deployment of the app with kuber --- z2/README.md | 182 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 182 insertions(+) create mode 100644 z2/README.md diff --git a/z2/README.md b/z2/README.md new file mode 100644 index 0000000..67985a3 --- /dev/null +++ b/z2/README.md @@ -0,0 +1,182 @@ +# Vigimétéo – Kubernetes Deployment (z2) + +--- + +## 1. Application description + +**Vigimétéo** is a weather monitoring web application. +Users can log in, browse weather stations, consult meteorological data (wind, temperature, pressure…) and manage objects depending on their role. + +The stack is made of three services: +- A **React** frontend served by Nginx +- A **Java / Vert.x** REST backend that exposes the API +- A **PostgreSQL** database that stores all data + +--- + +## 2. Containers used + +| Container | Image | Role | +|---|---|---| +| `vigimeteo-frontend` | `vigimeteo-frontend:latest` (built from `Front-end/Dockerfile`) | React SPA built with Vite, served by Nginx on port 80 | +| `vigimeteo-backend` | `vigimeteo-backend:latest` (built from `Back-end/Dockerfile`) | Java 17 / Vert.x REST API on port 8888. Connects to PostgreSQL using environment variables | +| `postgres` | `postgres:17-alpine` | PostgreSQL database. Automatically runs `init.sql` on first start to create tables and insert seed data | +| `busybox` (init) | `busybox:1.36` | Temporary init container inside the backend pod. Waits until PostgreSQL port 5432 is open before letting the backend start | + +--- + +## 3. Kubernetes objects + +| Kind | Name | Description | +|---|---|---| +| `Namespace` | `vigimeteo` | Isolates all objects of this application from the rest of the cluster | +| `PersistentVolume` | `vigimeteo-db-pv` | 1 Gi storage volume mapped to `~/vigimeteo-db-data` on the host node | +| `PersistentVolumeClaim` | `vigimeteo-db-pvc` | Request for storage, bound to the PV above. Used by the StatefulSet | +| `ConfigMap` | `vigimeteo-db-init` | Holds the SQL init script (`init.sql`). Mounted into the PostgreSQL container | +| `StatefulSet` | `vigimeteo-db` | Manages the PostgreSQL pod. Provides a stable name and stable storage | +| `Deployment` | `vigimeteo-backend` | Manages 2 replicas of the Vert.x backend | +| `Deployment` | `vigimeteo-frontend` | Manages 2 replicas of the Nginx/React frontend | +| `Service` (Headless) | `vigimeteo-db` | Gives the PostgreSQL pod a stable DNS name: `vigimeteo-db.vigimeteo.svc.cluster.local` | +| `Service` (NodePort) | `vigimeteo-backend-service` | Exposes the backend API on port **30888** (accessible from the host) | +| `Service` (NodePort) | `vigimeteo-frontend-service` | Exposes the frontend on port **30500** (accessible from the host) | + +--- + +## 4. Networks and volumes + +### Network +Kubernetes creates a virtual internal network for the `vigimeteo` namespace automatically. +- Pods communicate internally using **DNS service names** (e.g. `vigimeteo-db.vigimeteo.svc.cluster.local`). +- The frontend and backend are exposed externally via **NodePort** services. + +| Access | Address | +|---|---| +| Frontend (browser) | `http://localhost:30500` | +| Backend API | `http://localhost:30888` | +| Database (internal only) | `vigimeteo-db.vigimeteo.svc.cluster.local:5432` | + +### Volume +| Name | Type | Host path | Used by | +|---|---|---|---| +| `vigimeteo-db-pv` | PersistentVolume (hostPath) | `~/vigimeteo-db-data` | PostgreSQL StatefulSet | + +The volume is created by `prepare-app.sh` with `mkdir -p ~/vigimeteo-db-data`. +It persists data even after the application is stopped. + +--- + +## 5. Container configuration + +### Backend – environment variables + +The backend connects to the database using these environment variables set in `deployment.yaml`: + +| Variable | Value | +|---|---| +| `DB_HOST` | `vigimeteo-db.vigimeteo.svc.cluster.local` | +| `DB_PORT` | `5432` | +| `DB_NAME` | `postgres` | +| `DB_USER` | `postgres` | +| `DB_PASSWORD` | `admin` | + +### Backend – init container + +To avoid connection errors on startup, a `busybox` init container runs first and waits until PostgreSQL accepts connections on port 5432: + +```bash +until nc -z vigimeteo-db.vigimeteo.svc.cluster.local 5432; do sleep 3; done +``` + +### Database – init script + +The ConfigMap `vigimeteo-db-init` contains `init.sql` and is mounted into `/docker-entrypoint-initdb.d/` inside the PostgreSQL container. PostgreSQL automatically runs all `.sql` files in that folder on first startup. + +### Images + +Both images are built locally with `imagePullPolicy: IfNotPresent` so Kubernetes never tries to pull them from a registry. + +--- + +## 6. How to run the application + +### Prerequisites +- `docker` installed and running +- `kubectl` configured and connected to a cluster +- For **Minikube**: run `eval $(minikube docker-env)` first so images are built inside Minikube's daemon + +### Step 1 – Prepare (first time only) + +```bash +bash prepare-app.sh +``` + +This creates the PV host directory and builds the two Docker images. + +### Step 2 – Start + +```bash +bash start-app.sh +``` + +Applies all Kubernetes objects in the correct order and waits for PostgreSQL to be ready before deploying the backend. + +### Step 3 – Pause / restart + +There is no "pause" in Kubernetes. To stop traffic you can scale down replicas: + +```bash +kubectl scale deployment vigimeteo-backend vigimeteo-frontend --replicas=0 -n vigimeteo +``` + +To restart: + +```bash +kubectl scale deployment vigimeteo-backend vigimeteo-frontend --replicas=2 -n vigimeteo +``` + +### Step 4 – Delete + +```bash +bash stop-app.sh +``` + +This deletes the namespace (which removes all objects inside it) and the PersistentVolume. +The data folder `~/vigimeteo-db-data` is **not** deleted. To fully clean up: + +```bash +rm -rf ~/vigimeteo-db-data +``` + +--- + +## 7. How to access the application + +Once the app is started, open your browser at: + +**http://localhost:30500** + +### Test credentials + +| Role | Email | Password | +|---|---|---| +| Admin | `admin@a.com` | `azertyuiop` | +| Complexe user | `complexe@gmail.com` | `azertyuiop` | +| Regular user | `user@gmail.com` | `azertyuiop` | + +### Verify everything is running + +```bash +kubectl get all -n vigimeteo +``` + +All pods should show `1/1 Running`. + +--- + +## Troubleshooting + +**Pod stays `Pending`** → The PVC is not bound. Run `kubectl describe pod -n vigimeteo ` and check the events. Make sure `~/vigimeteo-db-data` exists. + +**Backend `CrashLoopBackOff`** → Check logs with `kubectl logs -n vigimeteo deployment/vigimeteo-backend`. Usually a DB connection issue. + +**Images not found** → For Minikube, run `eval $(minikube docker-env)` before `prepare-app.sh`.