adopt-a-street/COUCHDB_SETUP.md

CouchDB Setup Guide

This guide covers the setup and configuration of CouchDB for the Adopt-a-Street application.

Overview

CouchDB is the new primary database for Adopt-a-Street, replacing MongoDB. It provides better scalability, built-in replication, and a more flexible document model for our community street adoption platform.

Prerequisites

• Docker and Docker Compose (for local development)
• Kubernetes cluster (for production deployment)
• Node.js and npm/bun (for running scripts)

Local Development Setup

1. Using Docker Compose

Create a docker-compose.yml file in your project root:

version: '3.8'

services:
  couchdb:
    image: couchdb:3.3
    container_name: adopt-a-street-couchdb
    ports:
      - "5984:5984"
      - "4369:4369"
      - "9100:9100"
    environment:
      - COUCHDB_USER=admin
      - COUCHDB_PASSWORD=admin
      - COUCHDB_SECRET=some-random-secret-string
      - NODENAME=couchdb@localhost
    volumes:
      - couchdb_data:/opt/couchdb/data
      - ./couchdb/local.d:/opt/couchdb/etc/local.d
    restart: unless-stopped

  couchdb-exporter:
    image: gesellix/couchdb-exporter:latest
    container_name: adopt-a-street-couchdb-exporter
    ports:
      - "9100:9100"
    environment:
      - COUCHDB_URL=http://localhost:5984
      - COUCHDB_USER=admin
      - COUCHDB_PASSWORD=admin
    depends_on:
      - couchdb
    restart: unless-stopped

volumes:
  couchdb_data:

2. Configuration

Create the configuration directory and file:

mkdir -p couchdb/local.d
cat > couchdb/local.d/10-adopt-a-street.ini << 'EOF'
[cors]
origins = *
credentials = true
headers = accept, authorization, content-type, origin, referer, x-csrf-token
methods = GET, PUT, POST, HEAD, DELETE
max_age = 3600

[chttpd]
bind_address = 0.0.0.0
port = 5984

[couchdb]
enable_cors = true
single_node = false
EOF

3. Start CouchDB

docker-compose up -d

4. Verify Installation

# Check if CouchDB is running
curl http://localhost:5984/_up

# Expected response: {"status":"ok"}

Database Initialization

1. Create Database

# Using curl
curl -X PUT http://admin:admin@localhost:5984/adopt-a-street

# Or use the setup script
cd backend
bun run setup:couchdb

2. Create Indexes

The application will automatically create necessary indexes on startup. You can also create them manually:

# Create design document with indexes
curl -X PUT http://admin:admin@localhost:5984/adopt-a-street/_design/adopt-a-street \
  -H "Content-Type: application/json" \
  -d @couchdb-indexes.json

Environment Configuration

Update your .env file with CouchDB configuration:

# CouchDB Configuration
COUCHDB_URL=http://localhost:5984
COUCHDB_DB_NAME=adopt-a-street
COUCHDB_USER=admin
COUCHDB_PASSWORD=admin
COUCHDB_SECRET=some-random-secret-string

# Legacy MongoDB (keep for migration if needed)
# MONGO_URI=mongodb://localhost:27017/adopt-a-street

Migration from MongoDB

If you have existing data in MongoDB, use the migration script:

# From project root
bun scripts/migrate-to-couchdb.js

# Or with environment variables
COUCHDB_URL=http://localhost:5984 \
COUCHDB_DB=adopt-a-street \
MONGO_URI=mongodb://localhost:27017/adopt-a-street \
bun scripts/migrate-to-couchdb.js

Migration Process

1. Backup: Always backup your MongoDB data before migration
2. Schema Mapping: The script maps MongoDB collections to CouchDB document types
3. Relationships: Foreign keys are converted to document references
4. Indexes: Creates appropriate CouchDB indexes for performance
5. Validation: Verifies data integrity after migration

Production Deployment (Kubernetes)

1. Deploy CouchDB StatefulSet

# Apply CouchDB configuration
kubectl apply -f deploy/k8s/couchdb-configmap.yaml

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

# Wait for CouchDB to be ready
kubectl wait --for=condition=ready pod -l app=couchdb -n adopt-a-street --timeout=120s

2. Configure Secrets

# Copy and edit secrets template
cp deploy/k8s/secrets.yaml.example deploy/k8s/secrets.yaml

# Generate strong passwords
COUCHDB_PASSWORD=$(openssl rand -base64 32)
COUCHDB_SECRET=$(openssl rand -base64 32)

# Edit the secrets file with your values
nano deploy/k8s/secrets.yaml

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

3. Update Backend Configuration

The backend deployment is already configured to use CouchDB. Just ensure the secrets are properly set.

4. Verify Deployment

# Check pod status
kubectl get pods -n adopt-a-street -l app=couchdb

# Check logs
kubectl logs -f adopt-a-street-couchdb-0 -n adopt-a-street

# Port forward for testing
kubectl port-forward svc/adopt-a-street-couchdb 5984:5984 -n adopt-a-street

Monitoring and Maintenance

1. Health Checks

CouchDB provides built-in health endpoints:

# Basic health check
curl http://localhost:5984/_up

# Detailed status
curl http://localhost:5984/_stats

# Active tasks
curl http://localhost:5984/_active_tasks

2. Metrics

The CouchDB exporter provides Prometheus-compatible metrics:

# Access metrics
curl http://localhost:9100/metrics

3. Backup and Restore

Backup

# Create backup
curl -X GET http://admin:admin@localhost:5984/adopt-a-street/_all_docs?include_docs=true > backup.json

# Or use couchdb-dump
docker exec adopt-a-street-couchdb couchdb-dump -u admin -p admin -d adopt-a-street > backup.json

Restore

# Restore from backup
curl -X POST http://admin:admin@localhost:5984/adopt-a-street/_bulk_docs \
  -H "Content-Type: application/json" \
  -d @backup.json

4. Compaction

Regular compaction helps maintain performance:

# Compact database
curl -X POST http://admin:admin@localhost:5984/adopt-a-street/_compact

# Compact views
curl -X POST http://admin:admin@localhost:5984/adopt-a-street/_compact/design-doc-name

Performance Optimization

1. Indexing Strategy

• Create indexes for frequently queried fields
• Use partial indexes where possible
• Monitor index size and performance

2. Document Design

• Keep documents reasonably sized (< 1MB)
• Use appropriate document structure
• Avoid deeply nested documents

3. Query Optimization

• Use specific selectors in queries
• Limit result sets with limit and skip
• Use view functions for complex queries

Security Best Practices

1. Authentication

• Use strong passwords for admin users
• Create application-specific users with limited permissions
• Enable HTTPS in production

2. Authorization

• Implement proper validation in the application layer
• Use CouchDB's security features for additional protection
• Regularly review user permissions

3. Network Security

• Restrict access to CouchDB ports
• Use VPN or private networks for cluster communication
• Enable firewall rules as needed

Troubleshooting

Common Issues

1. Connection Refused

# Check if CouchDB is running
docker ps | grep couchdb

# Check logs
docker logs adopt-a-street-couchdb

2. Authentication Failed

# Verify credentials
curl -u admin:admin http://localhost:5984/_session

# Check user configuration
curl -u admin:admin http://localhost:5984/_config/admins

3. Database Not Found

# List databases
curl -u admin:admin http://localhost:5984/_all_dbs

# Create database
curl -X PUT -u admin:admin http://localhost:5984/adopt-a-street

4. Index Not Working

# Check index status
curl -u admin:admin http://localhost:5984/adopt-a-street/_index

# Rebuild index
curl -X POST -u admin:admin http://localhost:5984/adopt-a-street/_index/_design/adopt-a-street

Logs and Debugging

# View CouchDB logs
docker logs -f adopt-a-street-couchdb

# Enable debug logging (in local.ini)
[log]
level = debug

Additional Resources

• CouchDB Documentation
• CouchDB Best Practices
• Nano.js (Node.js Client)
• CouchDB Exporter

Support

For issues specific to Adopt-a-Street:

1. Check application logs for CouchDB-related errors
2. Verify environment configuration
3. Test CouchDB connectivity directly
4. Review migration logs if migrating from MongoDB

For general CouchDB issues, refer to the official CouchDB documentation and community forums.