# 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. The manifests are namespace-agnostic and can be deployed to any namespace of your choice.

## Namespace Selection

### Choosing a Namespace
Before deploying, decide which namespace to use:
- **Development**: `adopt-a-street-dev` or `dev`
- **Staging**: `adopt-a-street-staging` or `staging` 
- **Production**: `adopt-a-street-prod` or `prod`
- **Personal**: `adopt-a-street-<username>` for individual developers

### Namespace Best Practices
- Use descriptive names that indicate environment purpose
- Keep environments isolated in separate namespaces
- Use consistent naming conventions across teams
- Consider using prefixes like `adopt-a-street-` for clarity

### Creating a Namespace
```bash
# Create a new namespace
kubectl create namespace <your-namespace>

# Set as default namespace for current context
kubectl config set-context --current --namespace=<your-namespace>

# Or switch namespaces temporarily
kubectl namespace <your-namespace>
```

## 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
```bash
# Replace YOUR_GITEA_PASSWORD with your actual Gitea password
# Replace <your-namespace> with your chosen namespace
kubectl create secret docker-registry regcred \
  --docker-server=gitea-http.taildb3494.ts.net \
  --docker-username=will \
  --docker-password=YOUR_GITEA_PASSWORD \
  --namespace=<your-namespace>

# Examples:
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-dev

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-prod
```

### 2. Apply Configuration
```bash
# Apply all manifests to your chosen namespace
kubectl apply -f deploy/k8s/ -n <your-namespace>

# Or apply individually for more control:
kubectl apply -f deploy/k8s/configmap.yaml -n <your-namespace>
kubectl apply -f deploy/k8s/secrets.yaml -n <your-namespace>
kubectl apply -f deploy/k8s/couchdb-statefulset.yaml -n <your-namespace>
kubectl apply -f deploy/k8s/backend-deployment.yaml -n <your-namespace>
kubectl apply -f deploy/k8s/frontend-deployment.yaml -n <your-namespace>

# Examples for different environments:
kubectl apply -f deploy/k8s/ -n adopt-a-street-dev
kubectl apply -f deploy/k8s/ -n adopt-a-street-staging  
kubectl apply -f deploy/k8s/ -n adopt-a-street-prod
```

### 3. Verify Deployment
```bash
# Check all pods in your namespace
kubectl get pods -n <your-namespace>

# Check services in your namespace
kubectl get services -n <your-namespace>

# Check all resources in your namespace
kubectl get all -n <your-namespace>

# Check logs for specific deployments
kubectl logs -n <your-namespace> deployment/adopt-a-street-backend
kubectl logs -n <your-namespace> deployment/adopt-a-street-frontend

# Watch pod status
kubectl get pods -n <your-namespace> -w

# Check resource usage
kubectl top pods -n <your-namespace>
```

## 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

### Namespace-Related Issues

#### Wrong Namespace
```bash
# List all namespaces
kubectl get namespaces

# Check current namespace context
kubectl config view --minify | grep namespace

# Switch to correct namespace
kubectl config set-context --current --namespace=<your-namespace>

# Check resources across all namespaces
kubectl get pods --all-namespaces | grep adopt-a-street
```

#### Resources Not Found
```bash
# Verify resources exist in your namespace
kubectl get all -n <your-namespace>

# Check if resources are in a different namespace
kubectl get all --all-namespaces | grep adopt-a-street

# Get events from your namespace
kubectl get events -n <your-namespace> --sort-by='.lastTimestamp'
```

### Image Pull Issues
```bash
# Verify image pull secret in your namespace
kubectl get secret regcred -n <your-namespace> -o yaml

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

# Debug image pull errors
kubectl describe pod -l app=adopt-a-street-backend -n <your-namespace>
```

### CouchDB Connection Issues
```bash
# Check CouchDB pod in your namespace
kubectl logs -n <your-namespace> statefulset/adopt-a-street-couchdb

# Test connection from backend pod
kubectl exec -it deployment/adopt-a-street-backend -n <your-namespace> \
  -- curl http://adopt-a-street-couchdb:5984/_up

# Check CouchDB service
kubectl get service adopt-a-street-couchdb -n <your-namespace>
kubectl describe service adopt-a-street-couchdb -n <your-namespace>
```

### Health Check Failures
```bash
# Check backend health endpoint
kubectl exec -it deployment/adopt-a-street-backend -n <your-namespace> \
  -- curl http://localhost:5000/api/health

# Check frontend health endpoint
kubectl exec -it deployment/adopt-a-street-frontend -n <your-namespace> \
  -- curl http://localhost:80/health

# Check pod events for health check failures
kubectl describe pod -l app=adopt-a-street-backend -n <your-namespace>
```

### Multi-Environment Deployment

#### Deploying to Multiple Namespaces
```bash
# Deploy to development
kubectl apply -f deploy/k8s/ -n adopt-a-street-dev

# Deploy to staging  
kubectl apply -f deploy/k8s/ -n adopt-a-street-staging

# Deploy to production
kubectl apply -f deploy/k8s/ -n adopt-a-street-prod

# Compare deployments across namespaces
kubectl get deployments --all-namespaces | grep adopt-a-street
```

#### Environment-Specific Configuration
```bash
# Create environment-specific secrets
kubectl create secret generic jwt-secret-dev --from-literal=JWT_SECRET=$(openssl rand -base64 32) -n adopt-a-street-dev
kubectl create secret generic jwt-secret-prod --from-literal=JWT_SECRET=$(openssl rand -base64 32) -n adopt-a-street-prod

# Patch ConfigMaps for different environments
kubectl patch configmap adopt-a-street-config -n adopt-a-street-prod \
  --patch '{"data":{"NODE_ENV":"production"}}'
```

### Common Commands Reference

```bash
# Set default namespace for current session
kubectl config set-context --current --namespace=<your-namespace>

# View current context and namespace
kubectl config current-context
kubectl config view --minify

# Get resources in specific format
kubectl get pods -n <your-namespace> -o wide
kubectl get services -n <your-namespace> -o yaml

# Port forwarding for debugging
kubectl port-forward -n <your-namespace> service/adopt-a-street-backend 5000:5000
kubectl port-forward -n <your-namespace> service/adopt-a-street-frontend 3000:80

# Exec into pods for debugging
kubectl exec -it -n <your-namespace> deployment/adopt-a-street-backend -- /bin/bash
kubectl exec -it -n <your-namespace> deployment/adopt-a-street-frontend -- /bin/sh
```