will/adopt-a-street
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Complete CouchDB migration and Docker configuration

Browse Source 
- Add comprehensive CouchDB setup and configuration
- Update Docker files for CouchDB compatibility
- Create Kubernetes manifests for CouchDB deployment
- Add migration scripts and documentation
- Update seeding scripts to support both CouchDB and MongoDB
- Add docker-compose for local development
- Create comprehensive setup and deployment guides

🤖 Generated with [AI Assistant]

Co-Authored-By: AI Assistant <noreply@ai-assistant.com>
This commit is contained in:
William Valentin
2025-11-01 13:32:39 -07:00
parent df94c17e1f
commit 5aca521c52
949 changed files with 214621 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

380
COUCHDB_SETUP.md Normal file
View File

@@ -0,0 +1,380 @@
# 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:
```yaml
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:
```bash
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
```bash
docker-compose up -d
```
### 4. Verify Installation
```bash
# Check if CouchDB is running
curl http://localhost:5984/_up
# Expected response: {"status":"ok"}
```
## Database Initialization
### 1. Create Database
```bash
# 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:
```bash
# 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:
```bash
# 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:
```bash
# From project root
node 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 \
node 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
```bash
# 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
```bash
# 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
```bash
# 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:
```bash
# 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:
```bash
# Access metrics
curl http://localhost:9100/metrics
```
### 3. Backup and Restore
#### Backup
```bash
# 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
```bash
# 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:
```bash
# 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
```bash
# Check if CouchDB is running
docker ps | grep couchdb
# Check logs
docker logs adopt-a-street-couchdb
```
#### 2. Authentication Failed
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# View CouchDB logs
docker logs -f adopt-a-street-couchdb
# Enable debug logging (in local.ini)
[log]
level = debug
```
## Additional Resources
- [CouchDB Documentation](https://docs.couchdb.org/)
- [CouchDB Best Practices](https://docs.couchdb.org/en/stable/intro/best-practices.html)
- [Nano.js (Node.js Client)](https://github.com/apache/couchdb-nano)
- [CouchDB Exporter](https://github.com/gesellix/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.