feat(#37-41): Add domains, ideas, relationships, agents, widgets schema

Schema additions for issues #37-41: New models: - Domain (#37): Life domains (work, marriage, homelab, etc.) - Idea (#38): Brain dumps with pgvector embeddings - Relationship (#39): Generic entity linking (blocks, depends_on) - Agent (#40): ClawdBot agent tracking with metrics - AgentSession (#40): Conversation session tracking - WidgetDefinition (#41): HUD widget registry - UserLayout (#41): Per-user dashboard configuration Updated models: - Task, Event, Project: Added domainId foreign key - User, Workspace: Added new relations New enums: - IdeaStatus: CAPTURED, PROCESSING, ACTIONABLE, ARCHIVED, DISCARDED - RelationshipType: BLOCKS, BLOCKED_BY, DEPENDS_ON, etc. - AgentStatus: IDLE, WORKING, WAITING, ERROR, TERMINATED - EntityType: Added IDEA, DOMAIN Migration: 20260129182803_add_domains_ideas_agents_widgets
2026-01-29 12:29:21 -06:00
parent a220c2dc0a
commit 973502f26e
308 changed files with 18374 additions and 113 deletions
--- a/docs/1-getting-started/4-docker-deployment/QUICK-REFERENCE.md
+++ b/docs/1-getting-started/4-docker-deployment/QUICK-REFERENCE.md
@@ -0,0 +1,349 @@
+# Docker Quick Reference
+
+Quick command reference for Mosaic Stack Docker operations.
+
+## Starting Services
+
+```bash
+# Core services only (PostgreSQL, Valkey, API, Web)
+docker compose up -d
+
+# With Authentik OIDC
+docker compose --profile authentik up -d
+
+# With Ollama AI
+docker compose --profile ollama up -d
+
+# All services
+docker compose --profile full up -d
+
+# Or use Makefile
+make docker-up        # Core services
+make docker-up-full   # All services
+```
+
+## Stopping Services
+
+```bash
+# Stop (keeps data)
+docker compose down
+
+# Stop and remove volumes (deletes data!)
+docker compose down -v
+```
+
+## Viewing Status
+
+```bash
+# List running services
+docker compose ps
+
+# View logs (all services)
+docker compose logs -f
+
+# View logs (specific service)
+docker compose logs -f api
+
+# Last 100 lines
+docker compose logs --tail=100 api
+
+# Resource usage
+docker stats
+```
+
+## Service Management
+
+```bash
+# Restart all services
+docker compose restart
+
+# Restart specific service
+docker compose restart api
+
+# Rebuild and restart
+docker compose up -d --build
+
+# Pull latest images
+docker compose pull
+```
+
+## Database Operations
+
+```bash
+# PostgreSQL shell
+docker compose exec postgres psql -U mosaic -d mosaic
+
+# Run migrations
+docker compose exec api pnpm prisma:migrate:prod
+
+# Seed data
+docker compose exec api pnpm prisma:seed
+
+# Backup database
+docker compose exec postgres pg_dump -U mosaic mosaic > backup.sql
+
+# Restore database
+cat backup.sql | docker compose exec -T postgres psql -U mosaic -d mosaic
+```
+
+## Cache Operations
+
+```bash
+# Valkey CLI
+docker compose exec valkey valkey-cli
+
+# Check cache health
+docker compose exec valkey valkey-cli ping
+
+# Flush cache
+docker compose exec valkey valkey-cli FLUSHALL
+```
+
+## Container Access
+
+```bash
+# API container shell
+docker compose exec api sh
+
+# Web container shell
+docker compose exec web sh
+
+# Run command in container
+docker compose exec api node -v
+```
+
+## Debugging
+
+```bash
+# Check service health
+docker compose ps
+
+# View container details
+docker inspect mosaic-api
+
+# Check networks
+docker network ls
+docker network inspect mosaic-internal
+
+# Check volumes
+docker volume ls
+docker volume inspect mosaic-postgres-data
+
+# Test connectivity
+docker compose exec api nc -zv postgres 5432
+docker compose exec api nc -zv valkey 6379
+```
+
+## Health Endpoints
+
+```bash
+# API health
+curl http://localhost:3001/health
+
+# Web (returns HTML)
+curl http://localhost:3000
+
+# Authentik health (if enabled)
+curl http://localhost:9000/-/health/live/
+
+# Ollama health (if enabled)
+curl http://localhost:11434/api/tags
+```
+
+## Cleanup
+
+```bash
+# Remove stopped containers
+docker compose down
+
+# Remove containers and volumes
+docker compose down -v
+
+# Remove all unused Docker resources
+docker system prune -a
+
+# Remove unused volumes only
+docker volume prune
+```
+
+## Environment Management
+
+```bash
+# Check current environment
+docker compose config
+
+# Validate compose file
+docker compose config --quiet
+
+# Use specific env file
+docker compose --env-file .env.production up -d
+```
+
+## Profiles
+
+```bash
+# Available profiles
+# - authentik: Authentik OIDC stack
+# - ollama: Ollama AI service
+# - full: All optional services
+
+# Set profile via environment
+export COMPOSE_PROFILES=authentik,ollama
+docker compose up -d
+
+# Or in .env file
+echo "COMPOSE_PROFILES=full" >> .env
+```
+
+## Troubleshooting
+
+```bash
+# Container won't start - check logs
+docker compose logs <service>
+
+# Port conflict - check what's using the port
+lsof -i :3001
+
+# Permission errors - check permissions
+docker compose exec postgres ls -la /var/lib/postgresql/data
+
+# Network issues - recreate networks
+docker compose down
+docker network prune
+docker compose up -d
+
+# Volume issues - check volume
+docker volume inspect mosaic-postgres-data
+
+# Reset everything (DANGER: deletes all data)
+docker compose down -v
+docker system prune -af
+docker volume prune -f
+```
+
+## Performance Tuning
+
+```bash
+# View resource usage
+docker stats
+
+# Limit container resources (in docker-compose.override.yml)
+services:
+  api:
+    deploy:
+      resources:
+        limits:
+          cpus: '1.0'
+          memory: 1G
+
+# Adjust PostgreSQL settings in .env
+POSTGRES_SHARED_BUFFERS=512MB
+POSTGRES_EFFECTIVE_CACHE_SIZE=2GB
+
+# Adjust Valkey memory in .env
+VALKEY_MAXMEMORY=512mb
+```
+
+## Backup & Restore
+
+```bash
+# Backup PostgreSQL database
+docker compose exec postgres pg_dump -U mosaic mosaic > backup-$(date +%Y%m%d).sql
+
+# Backup volume
+docker run --rm \
+  -v mosaic-postgres-data:/data \
+  -v $(pwd):/backup \
+  alpine tar czf /backup/postgres-backup.tar.gz /data
+
+# Restore database
+cat backup-20260128.sql | docker compose exec -T postgres psql -U mosaic -d mosaic
+
+# Restore volume
+docker run --rm \
+  -v mosaic-postgres-data:/data \
+  -v $(pwd):/backup \
+  alpine tar xzf /backup/postgres-backup.tar.gz -C /
+```
+
+## Security
+
+```bash
+# Scan images for vulnerabilities
+docker scout cves mosaic-api
+
+# Check running processes in container
+docker compose exec api ps aux
+
+# View container security options
+docker inspect mosaic-api --format='{{.HostConfig.SecurityOpt}}'
+
+# Rotate secrets (update .env, then)
+docker compose up -d --force-recreate
+```
+
+## Makefile Commands
+
+```bash
+make help                 # Show all commands
+make docker-up            # Start core services
+make docker-up-full       # Start all services
+make docker-down          # Stop services
+make docker-logs          # View logs
+make docker-ps            # Service status
+make docker-build         # Rebuild images
+make docker-restart       # Restart services
+make docker-test          # Run smoke test
+make docker-clean         # Remove containers and volumes
+```
+
+## npm Scripts
+
+```bash
+pnpm docker:up            # Start services
+pnpm docker:down          # Stop services
+pnpm docker:logs          # View logs
+pnpm docker:ps            # Service status
+pnpm docker:build         # Rebuild images
+pnpm docker:restart       # Restart services
+pnpm test:docker          # Run integration tests
+```
+
+## One-Liners
+
+```bash
+# Quick health check all services
+docker compose ps | grep -E 'Up|healthy'
+
+# Follow logs for all services with timestamps
+docker compose logs -f --timestamps
+
+# Restart unhealthy services
+docker compose ps --format json | jq -r 'select(.Health == "unhealthy") | .Service' | xargs docker compose restart
+
+# Show disk usage by service
+docker system df -v
+
+# Export all logs to file
+docker compose logs > logs-$(date +%Y%m%d-%H%M%S).txt
+
+# Check which ports are exposed
+docker compose ps --format json | jq -r '.[] | "\(.Service): \(.Publishers)"'
+```
+
+## Service URLs (Default Ports)
+
+- **Web**: http://localhost:3000
+- **API**: http://localhost:3001
+- **API Health**: http://localhost:3001/health
+- **PostgreSQL**: localhost:5432
+- **Valkey**: localhost:6379
+- **Authentik**: http://localhost:9000 (if enabled)
+- **Ollama**: http://localhost:11434 (if enabled)
+- **Prisma Studio**: http://localhost:5555 (when running)
+
+## Next Steps
+
+- [Full Deployment Guide](README.md)
+- [Configuration Reference](../3-configuration/3-docker.md)
+- [Troubleshooting Guide](README.md#troubleshooting)