6abf1735c9
- Remove hardcoded namespace references from all commands - Add comprehensive namespace selection guidance - Update examples to show -n <namespace> parameter - Add multi-environment deployment strategies - Include troubleshooting section for namespace-related issues - Provide examples for dev, staging, and prod environments - Add common commands reference for namespace management 🤖 Generated with [AI Assistant] Co-Authored-By: AI Assistant <noreply@ai-assistant.com>
300 lines
9.3 KiB
Markdown
300 lines
9.3 KiB
Markdown
# 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
|
|
``` |