From 118fce5f8980a1757222e85e8909801915d63279 Mon Sep 17 00:00:00 2001
From: Aitect <lean-architect@proton.me>
Date: Tue, 5 Aug 2025 08:26:59 +0000
Subject: [PATCH] feat: add CouchDB setup and configuration files for local
 development

---
 .gitignore                 |   3 +
 README.md                  |  13 +++-
 couchdb/.env.example       |  16 ++++
 couchdb/README.md          | 151 +++++++++++++++++++++++++++++++++++++
 couchdb/docker-compose.yml |  34 +++++++++
 couchdb/local.ini          |  11 +++
 6 files changed, 227 insertions(+), 1 deletion(-)
 create mode 100644 couchdb/.env.example
 create mode 100644 couchdb/README.md
 create mode 100644 couchdb/docker-compose.yml
 create mode 100644 couchdb/local.ini

diff --git a/.gitignore b/.gitignore
index a547bf3..a739264 100644
--- a/.gitignore
+++ b/.gitignore
@@ -12,6 +12,9 @@ dist
 dist-ssr
 *.local
 
+# Environment files
+.env
+
 # Editor directories and files
 .vscode/*
 !.vscode/extensions.json
diff --git a/README.md b/README.md
index ff9b814..bf2c1fb 100644
--- a/README.md
+++ b/README.md
@@ -51,7 +51,18 @@ npm run preview
 
 This will serve the production build at http://localhost:4173 (or another port if 4173 is in use).
 
+## Local Database Setup
+
+For development and debugging, this project uses CouchDB. See the [`couchdb/`](./couchdb/) directory for complete setup instructions and Docker configuration.
+
+Quick start:
+```bash
+cd couchdb
+cp .env.example .env
+docker-compose up -d
+```
+
 ## Additional Scripts
 
 - `npm run lint` - Run ESLint to check code quality
-- `npm test` - Run tests (if configured)
\ No newline at end of file
+- `npm test` - Run tests (if configured)
diff --git a/couchdb/.env.example b/couchdb/.env.example
new file mode 100644
index 0000000..4c87a5c
--- /dev/null
+++ b/couchdb/.env.example
@@ -0,0 +1,16 @@
+# CouchDB Configuration
+# Copy this file to .env and customize as needed
+
+# Admin credentials
+COUCHDB_USER=admin
+COUCHDB_PASSWORD=password
+
+# Port configuration
+COUCHDB_PORT=5984
+
+# CORS Configuration
+# For production, edit local.ini to replace origins = * with your specific domain
+# Example: origins = https://yourdomain.com,https://www.yourdomain.com
+
+# Optional: Additional CouchDB configuration
+# COUCHDB_SECRET=mysecretkey
diff --git a/couchdb/README.md b/couchdb/README.md
new file mode 100644
index 0000000..976ad4f
--- /dev/null
+++ b/couchdb/README.md
@@ -0,0 +1,151 @@
+# CouchDB Local Development Setup
+
+This directory contains everything needed to run a local CouchDB instance for development and debugging.
+
+## Prerequisites
+
+- Docker installed on your system
+- Docker Compose
+
+## Quick Start
+
+1. Copy the environment file:
+   ```bash
+   cp .env.example .env
+   ```
+
+2. (Optional) Edit `.env` to customize your settings
+
+3. Start CouchDB:
+   ```bash
+   docker-compose up -d
+   ```
+
+4. Access Fauxton web interface at: http://localhost:5984/_utils
+
+## Configuration
+
+### Environment Variables
+
+The following environment variables can be configured in your `.env` file:
+
+- `COUCHDB_USER` - Admin username (default: admin)
+- `COUCHDB_PASSWORD` - Admin password (default: password)
+- `COUCHDB_PORT` - Port to expose CouchDB on (default: 5984)
+
+### Default Credentials
+
+- **Username**: admin
+- **Password**: password
+
+### CORS Configuration
+
+CORS (Cross-Origin Resource Sharing) is pre-configured to allow requests from web applications. The configuration is in `local.ini` and includes:
+
+- **Origins**: `*` (allows all origins - customize for production)
+- **Methods**: GET, PUT, POST, HEAD, DELETE
+- **Headers**: accept, authorization, content-type, origin, referer, x-csrf-token
+- **Credentials**: Enabled
+
+> **⚠️ Production Note**: The CORS configuration allows all origins (`*`) for development convenience. In production, replace `*` with your specific domain(s) in `local.ini`.
+
+> **⚠️ Security Note**: These default credentials are for development only. Use secure credentials in production environments.
+
+## Usage
+
+### Starting the Database
+
+```bash
+# Start CouchDB in the background
+docker-compose up -d
+
+# Start with logs visible
+docker-compose up
+```
+
+### Stopping the Database
+
+```bash
+# Stop the container
+docker-compose down
+
+# Stop and remove volumes (⚠️ This will delete all data)
+docker-compose down -v
+```
+
+### Viewing Logs
+
+```bash
+# View current logs
+docker-compose logs
+
+# Follow logs in real-time
+docker-compose logs -f
+```
+
+## Accessing CouchDB
+
+### Web Interface (Fauxton)
+- URL: http://localhost:5984/_utils
+- Login with the credentials from your `.env` file
+
+### REST API
+- Base URL: http://localhost:5984
+- Authentication: HTTP Basic Auth
+
+### Example API Calls
+
+```bash
+# Check if CouchDB is running
+curl http://localhost:5984/
+
+# Create a new database
+curl -X PUT http://admin:password@localhost:5984/mydb
+
+# List all databases
+curl http://admin:password@localhost:5984/_all_dbs
+
+# Create a document
+curl -X POST http://admin:password@localhost:5984/mydb \
+  -H "Content-Type: application/json" \
+  -d '{"name": "test document", "type": "example"}'
+
+# Test CORS (from browser or web app)
+fetch('http://localhost:5984/', {
+  method: 'GET',
+  credentials: 'include'
+}).then(response => response.json()).then(data => console.log(data));
+  -d '{"name": "test document", "type": "example"}'
+```
+
+## Data Persistence
+
+Database data is persisted in a Docker volume named `couchdb_data`. This means your data will survive container restarts but will be lost if you run `docker-compose down -v`.
+
+## Troubleshooting
+
+### Container won't start
+- Check if port 5984 is already in use: `lsof -i :5984`
+- View container logs: `docker-compose logs`
+
+### Can't access Fauxton
+- Ensure the container is running: `docker-compose ps`
+- Check if the port is properly mapped: `docker port couchdb-dev`
+
+### Reset everything
+```bash
+# Stop containers and remove all data
+docker-compose down -v
+
+# Remove the Docker image (forces fresh download)
+docker rmi couchdb:3.3
+
+# Start fresh
+docker-compose up -d
+```
+
+## Development Tips
+
+1. **Database Setup Scripts**: You can add initialization scripts in the `scripts/` directory
+2. **Backup**: Use `docker exec couchdb-dev couchdb-backup` for backups
+3. **Monitoring**: Access `http://localhost:5984/_stats` for database statistics
diff --git a/couchdb/docker-compose.yml b/couchdb/docker-compose.yml
new file mode 100644
index 0000000..57c196a
--- /dev/null
+++ b/couchdb/docker-compose.yml
@@ -0,0 +1,34 @@
+version: '3.8'
+
+services:
+  couchdb:
+    image: couchdb:3.3
+    container_name: couchdb-dev
+    environment:
+      - COUCHDB_USER=${COUCHDB_USER:-admin}
+      - COUCHDB_PASSWORD=${COUCHDB_PASSWORD:-password}
+    ports:
+      - "${COUCHDB_PORT:-5984}:5984"
+    volumes:
+      - couchdb_data:/opt/couchdb/data
+      - couchdb_config:/opt/couchdb/etc
+      - ./local.ini:/opt/couchdb/etc/local.d/local.ini
+    restart: unless-stopped
+    networks:
+      - couchdb_network
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:5984/_up"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 10s
+
+volumes:
+  couchdb_data:
+    driver: local
+  couchdb_config:
+    driver: local
+
+networks:
+  couchdb_network:
+    driver: bridge
diff --git a/couchdb/local.ini b/couchdb/local.ini
new file mode 100644
index 0000000..c9c7ef2
--- /dev/null
+++ b/couchdb/local.ini
@@ -0,0 +1,11 @@
+[httpd]
+enable_cors = true
+
+[cors]
+origins = *
+credentials = true
+methods = GET, PUT, POST, HEAD, DELETE, OPTIONS
+headers = accept, authorization, content-type, origin, referer, x-csrf-token, if-match, destination
+
+[chttpd]
+enable_cors = true