adopt-a-street/deploy/k8s/DEPLOYMENT_GUIDE.md

CouchDB Deployment Configuration Guide

Overview

This guide covers the configuration changes needed to deploy Adopt-a-Street with CouchDB on the Raspberry Pi Kubernetes cluster.

Changes Made

1. ConfigMap Updates (configmap.yaml)

✅ Already configured for CouchDB:

• COUCHDB_URL: "http://adopt-a-street-couchdb:5984"
• COUCHDB_DB_NAME: "adopt-a-street"
• Removed MongoDB references

2. Secrets Configuration (secrets.yaml)

✅ Generated secure credentials:

• JWT_SECRET: Generated secure random token
• COUCHDB_USER: "admin"
• COUCHDB_PASSWORD: Generated secure random password
• COUCHDB_SECRET: Generated secure random token

3. Backend Deployment Updates (backend-deployment.yaml)

✅ Updated configuration:

• Image: gitea-http.taildb3494.ts.net:will/adopt-a-street/backend:latest
• Added image pull secret for gitea registry
• Environment variables configured for CouchDB
• Health checks using /api/health endpoint
• Resource limits optimized for Raspberry Pi 5 (ARM64)

4. Frontend Deployment Updates (frontend-deployment.yaml)

✅ Updated configuration:

• Image: gitea-http.taildb3494.ts.net:will/adopt-a-street/frontend:latest
• Added image pull secret for gitea registry
• Health checks using /health endpoint
• Resource limits optimized for Raspberry Pi

5. Image Pull Secret (image-pull-secret.yaml)

✅ Created template for gitea registry authentication

Deployment Steps

1. Create Image Pull Secret

# Replace YOUR_GITEA_PASSWORD with your actual Gitea password
kubectl create secret docker-registry regcred \
  --docker-server=gitea-http.taildb3494.ts.net \
  --docker-username=will \
  --docker-password=YOUR_GITEA_PASSWORD \
  --namespace=adopt-a-street

2. Apply Configuration

# Apply ConfigMap
kubectl apply -f deploy/k8s/configmap.yaml

# Apply Secrets
kubectl apply -f deploy/k8s/secrets.yaml

# Apply CouchDB StatefulSet
kubectl apply -f deploy/k8s/couchdb-statefulset.yaml

# Apply Backend Deployment
kubectl apply -f deploy/k8s/backend-deployment.yaml

# Apply Frontend Deployment
kubectl apply -f deploy/k8s/frontend-deployment.yaml

3. Verify Deployment

# Check all pods
kubectl get pods -n adopt-a-street

# Check services
kubectl get services -n adopt-a-street

# Check logs
kubectl logs -n adopt-a-street deployment/adopt-a-street-backend
kubectl logs -n adopt-a-street deployment/adopt-a-street-frontend

Environment Variables Summary

ConfigMap Variables

• COUCHDB_URL: "http://adopt-a-street-couchdb:5984"
• COUCHDB_DB_NAME: "adopt-a-street"
• PORT: "5000"
• NODE_ENV: "production"
• FRONTEND_URL: "http://adopt-a-street.local"

Secret Variables

• JWT_SECRET: Secure random token
• COUCHDB_USER: "admin"
• COUCHDB_PASSWORD: Secure random password
• COUCHDB_SECRET: Secure random token
• Cloudinary credentials (placeholders)

Health Checks

Backend Health Check

• Endpoint: /api/health
• Method: GET
• Expected Response: {"status": "healthy", "database": "connected"}

Frontend Health Check

• Endpoint: /health
• Method: GET
• Expected Response: "healthy\n"

Resource Limits

Backend (per replica)

• Memory Request: 256Mi, Limit: 512Mi
• CPU Request: 100m, Limit: 500m
• Architecture: ARM64 (Pi 5 preferred)

Frontend (per replica)

• Memory Request: 64Mi, Limit: 128Mi
• CPU Request: 50m, Limit: 200m
• Architecture: Any (lightweight)

Security Notes

1. Secrets Management: secrets.yaml is in .gitignore and should never be committed
2. Generated Passwords: All passwords and secrets were generated using openssl rand -base64 32
3. Production Changes: Change default usernames and passwords before production deployment
4. Image Registry: Gitea registry requires authentication via image pull secrets

Troubleshooting

Image Pull Issues

# Verify image pull secret
kubectl get secret regcred -n adopt-a-street -o yaml

# Test image pull
kubectl run test-pod --image=gitea-http.taildb3494.ts.net:will/adopt-a-street/backend:latest --dry-run=client -o yaml

CouchDB Connection Issues

# Check CouchDB pod
kubectl logs -n adopt-a-street statefulset/adopt-a-street-couchdb

# Test connection from backend pod
kubectl exec -it deployment/adopt-a-street-backend -- curl http://adopt-a-street-couchdb:5984/_up

Health Check Failures

# Check backend health endpoint
kubectl exec -it deployment/adopt-a-street-backend -- curl http://localhost:5000/api/health

# Check frontend health endpoint
kubectl exec -it deployment/adopt-a-street-frontend -- curl http://localhost:80/health