feat: add local Kubernetes (Minikube) configurations and architecture documentation

Author: zavxai

.gitignore

@@ -37,3 +37,7 @@ opencode.json
 *.tsbuildinfo
 .vercel
 !.vercel/project.json
+
+# Kubernetes Secrets
+kubernetes/secrets.yaml
+

README.md

@@ -356,3 +356,62 @@ AI pipeline steps (the LangGraph RAG Agentic Chat, prompt revisions, document gr
 **Keeping the free-tier API warm:** Render's free instance sleeps after 15 min idle. GitHub Actions cron is too unreliable for short-interval keep-alive pings, so an external pinger ([cron-job.org](https://cron-job.org)) does a `GET https://api.inferr.xyz/health` every 10 min, restricted to hours 0–18 UTC (~06:00–24:00 IST) to stay within the 750 hr/month budget. The instance is allowed to sleep overnight; the web app's wake overlay (`apps/web/src/lib/server-status.tsx`) covers the first cold request.
 
 **Web (Vercel):** Set `NEXT_PUBLIC_API_URL` to the Render API URL. `vercel.json` at root handles the monorepo build pointing to `apps/web`.
+
+---
+
+## Kubernetes (Local Deployment)
+
+This project contains a complete, local Kubernetes deployment setup located in the [kubernetes/](file:///home/johnvesslyalti/johnvesslyalti_workspace/inferr/kubernetes/) directory. This allows you to run, manage, and test the entire backend infrastructure (NestJS API, Postgres with pgvector, Redis, migrations, and cronjobs) inside a local Kubernetes cluster.
+
+### Architecture
+![Kubernetes Architecture Diagram](docs/k8s_architecture.jpg)
+
+### Prerequisites
+* **Docker**
+* **Minikube**
+* **kubectl** & **Helm**
+
+### Launching the Cluster Locally
+1. **Start Minikube**:
+   ```bash
+   minikube start --driver=docker
+   ```
+2. **Build the API container inside Minikube**:
+   Build the NestJS API container image directly in the Minikube registry:
+   ```bash
+   minikube image build -t inferr-api:latest .
+   ```
+3. **Apply the manifests**:
+   Deploy all resources (Secrets, ConfigMaps, Postgres StatefulSet, Redis, API, and Ingress) to your cluster:
+   ```bash
+   kubectl apply -f kubernetes/
+   ```
+4. **Enable Ingress**:
+   Enable the Nginx Ingress Controller addon:
+   ```bash
+   minikube addons enable ingress
+   ```
+
+### Accessing the API
+1. Map the domain `api.inferr.local` to your Minikube IP:
+   ```bash
+   echo "$(minikube ip) api.inferr.local" | sudo tee -a /etc/hosts
+   ```
+2. Open `http://api.inferr.local/health` in your browser. You should receive:
+   ```json
+   { "status": "ok" }
+   ```
+
+### Managing the Pipeline
+* **Trigger the daily scraper manually**:
+  ```bash
+  kubectl create job --from=cronjob/scraper-cronjob scraper-manual-run
+  ```
+* **View the scraper logs**:
+  ```bash
+  kubectl logs -f -l job-name=scraper-manual-run
+  ```
+* **Verify Pod status**:
+  ```bash
+  kubectl get pods
+  ```

docs/k8s_architecture.jpg

@@ -0,0 +1,52 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: api
+  namespace: default
+  labels:
+    app: api
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: api
+  template:
+    metadata:
+      labels:
+        app: api
+    spec:
+      initContainers:
+        - name: wait-for-postgres
+          image: busybox:1.36
+          command:
+            - sh
+            - -c
+            - |
+              until nc -z -w 2 postgres-service 5432; do
+                echo "Waiting for postgres-service:5432..."
+                sleep 2
+              done
+      containers:
+        - name: api
+          image: inferr-api:latest
+          imagePullPolicy: IfNotPresent
+          ports:
+            - containerPort: 3001
+              name: http
+          envFrom:
+            - configMapRef:
+                name: api-config
+            - secretRef:
+                name: api-secrets
+          livenessProbe:
+            httpGet:
+              path: /health
+              port: 3001
+            initialDelaySeconds: 15
+            periodSeconds: 10
+          readinessProbe:
+            httpGet:
+              path: /health
+              port: 3001
+            initialDelaySeconds: 15
+            periodSeconds: 10

kubernetes/api-deployment.yaml

@@ -0,0 +1,13 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: api-service
+  namespace: default
+spec:
+  ports:
+    - port: 3001
+      targetPort: 3001
+      name: http
+  selector:
+    app: api
+  type: ClusterIP

kubernetes/api-service.yaml

@@ -0,0 +1,18 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: api-config
+  namespace: default
+data:
+  DB_HOST: "postgres-service"
+  DB_PORT: "5432"
+  DB_USER: "postgres"
+  DB_NAME: "ai_feed"
+  DB_SSL: "false"
+  API_PORT: "3001"
+  REDIS_HOST: "redis-service"
+  REDIS_PORT: "6379"
+  NODE_ENV: "production"
+  GOOGLE_CALLBACK_URL: "http://api.inferr.local/auth/google/callback"
+  GOOGLE_MCP_CALLBACK_URL: "http://api.inferr.local/auth/google/mcp-callback"
+  API_URL: "https://api.inferr.local"

kubernetes/configmap.yaml

@@ -0,0 +1,18 @@
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: api-ingress
+  namespace: default
+spec:
+  ingressClassName: nginx
+  rules:
+    - host: api.inferr.local
+      http:
+        paths:
+          - path: /
+            pathType: Prefix
+            backend:
+              service:
+                name: api-service
+                port:
+                  number: 3001

kubernetes/ingress.yaml

@@ -0,0 +1,11 @@
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: postgres-pvc
+  namespace: default
+spec:
+  accessModes:
+    - ReadWriteOnce
+  resources:
+    requests:
+      storage: 1Gi

kubernetes/postgres-pvc.yaml

@@ -0,0 +1,12 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: postgres-service
+  namespace: default
+spec:
+  ports:
+    - port: 5432
+      targetPort: 5432
+  selector:
+    app: postgres
+  type: ClusterIP

kubernetes/postgres-service.yaml

@@ -0,0 +1,39 @@
+apiVersion: apps/v1
+kind: StatefulSet
+metadata:
+  name: postgres
+  namespace: default
+spec:
+  serviceName: postgres-service
+  replicas: 1
+  selector:
+    matchLabels:
+      app: postgres
+  template:
+    metadata:
+      labels:
+        app: postgres
+    spec:
+      containers:
+        - name: postgres
+          image: pgvector/pgvector:pg16
+          ports:
+            - containerPort: 5432
+              name: postgres
+          env:
+            - name: POSTGRES_USER
+              value: "postgres"
+            - name: POSTGRES_DB
+              value: "ai_feed"
+            - name: POSTGRES_PASSWORD
+              valueFrom:
+                secretKeyRef:
+                  name: api-secrets
+                  key: DB_PASS
+          volumeMounts:
+            - name: postgres-storage
+              mountPath: /var/lib/postgresql/data
+      volumes:
+        - name: postgres-storage
+          persistentVolumeClaim:
+            claimName: postgres-pvc