feat: add flexible docker-compose architecture with profiles

- Add OpenBao services to docker-compose.yml with profiles (openbao, full)
- Add docker-compose.build.yml for local builds vs registry pulls
- Make PostgreSQL and Valkey optional via profiles (database, cache)
- Create example compose files for common deployment scenarios:
  - docker/docker-compose.example.turnkey.yml (all bundled)
  - docker/docker-compose.example.external.yml (all external)
  - docker/docker.example.hybrid.yml (mixed deployment)
- Update documentation:
  - Enhance .env.example with profiles and external service examples
  - Update README.md with deployment mode quick starts
  - Add deployment scenarios to docs/OPENBAO.md
  - Create docker/DOCKER-COMPOSE-GUIDE.md with comprehensive guide
- Clean up repository structure:
  - Move shell scripts to scripts/ directory
  - Move documentation to docs/ directory
  - Move docker compose examples to docker/ directory
- Configure for external Authentik with internal services:
  - Comment out Authentik services (using external OIDC)
  - Comment out unused volumes for disabled services
  - Keep postgres, valkey, openbao as internal services

This provides a flexible deployment architecture supporting turnkey,
production (all external), and hybrid configurations via Docker Compose
profiles.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.env.example

@@ -19,13 +19,18 @@ NEXT_PUBLIC_API_URL=http://localhost:3001
 # ======================
 # PostgreSQL Database
 # ======================
+# Bundled PostgreSQL (when database profile enabled)
 # SECURITY: Change POSTGRES_PASSWORD to a strong random password in production
-DATABASE_URL=postgresql://mosaic:REPLACE_WITH_SECURE_PASSWORD@localhost:5432/mosaic
+DATABASE_URL=postgresql://mosaic:REPLACE_WITH_SECURE_PASSWORD@postgres:5432/mosaic
 POSTGRES_USER=mosaic
 POSTGRES_PASSWORD=REPLACE_WITH_SECURE_PASSWORD
 POSTGRES_DB=mosaic
 POSTGRES_PORT=5432
 
+# External PostgreSQL (managed service)
+# Disable 'database' profile and point DATABASE_URL to your external instance
+# Example: DATABASE_URL=postgresql://user:pass@rds.amazonaws.com:5432/mosaic
+
 # PostgreSQL Performance Tuning (Optional)
 POSTGRES_SHARED_BUFFERS=256MB
 POSTGRES_EFFECTIVE_CACHE_SIZE=1GB
@@ -34,12 +39,18 @@ POSTGRES_MAX_CONNECTIONS=100
 # ======================
 # Valkey Cache (Redis-compatible)
 # ======================
-VALKEY_URL=redis://localhost:6379
-VALKEY_HOST=localhost
+# Bundled Valkey (when cache profile enabled)
+VALKEY_URL=redis://valkey:6379
+VALKEY_HOST=valkey
 VALKEY_PORT=6379
 # VALKEY_PASSWORD=       # Optional: Password for Valkey authentication
 VALKEY_MAXMEMORY=256mb
 
+# External Redis/Valkey (managed service)
+# Disable 'cache' profile and point VALKEY_URL to your external instance
+# Example: VALKEY_URL=redis://elasticache.amazonaws.com:6379
+# Example with auth: VALKEY_URL=redis://:password@redis.example.com:6379
+
 # Knowledge Module Cache Configuration
 # Set KNOWLEDGE_CACHE_ENABLED=false to disable caching (useful for development)
 KNOWLEDGE_CACHE_ENABLED=true
@@ -113,16 +124,28 @@ ENCRYPTION_KEY=REPLACE_WITH_64_CHAR_HEX_STRING_GENERATE_WITH_OPENSSL_RAND_HEX_32
 # OpenBao Secrets Management
 # ======================
 # OpenBao provides Transit encryption for sensitive credentials
+# Enable with: COMPOSE_PROFILES=openbao or COMPOSE_PROFILES=full
 # Auto-initialized on first run via openbao-init sidecar
+
+# Bundled OpenBao (when openbao profile enabled)
 OPENBAO_ADDR=http://openbao:8200
 OPENBAO_PORT=8200
 
+# External OpenBao/Vault (managed service)
+# Disable 'openbao' profile and set OPENBAO_ADDR to your external instance
+# Example: OPENBAO_ADDR=https://vault.example.com:8200
+# Example: OPENBAO_ADDR=https://vault.hashicorp.com:8200
+
 # AppRole Authentication (Optional)
 # If not set, credentials are read from /openbao/init/approle-credentials volume
-# These env vars are useful for testing or when running outside Docker
+# Required when using external OpenBao
 # OPENBAO_ROLE_ID=your-role-id-here
 # OPENBAO_SECRET_ID=your-secret-id-here
 
+# Fallback Mode
+# When OpenBao is unavailable, API automatically falls back to AES-256-GCM
+# encryption using ENCRYPTION_KEY. This provides graceful degradation.
+
 # ======================
 # Ollama (Optional AI Service)
 # ======================
@@ -161,24 +184,35 @@ NODE_ENV=development
 # ======================
 # Docker Image Configuration
 # ======================
-# Docker image tag for swarm deployments
+# Docker image tag for pulling pre-built images from git.mosaicstack.dev registry
+# Used by docker-compose.yml (pulls images) and docker-swarm.yml
+# For local builds, use docker-compose.build.yml instead
 # Options:
-#   - latest: Pull latest stable images from registry (default for production)
-#   - dev: Pull development images from registry
-#   - local: Use locally built images (for development)
+#   - dev: Pull development images from registry (default, built from develop branch)
+#   - latest: Pull latest stable images from registry (built from main branch)
 #   - <commit-sha>: Use specific commit SHA tag (e.g., 658ec077)
 #   - <version>: Use specific version tag (e.g., v1.0.0)
-IMAGE_TAG=latest
+IMAGE_TAG=dev
 
 # ======================
 # Docker Compose Profiles
 # ======================
-# Uncomment to enable optional services:
-# COMPOSE_PROFILES=authentik,ollama  # Enable both Authentik and Ollama
-# COMPOSE_PROFILES=full              # Enable all optional services
-# COMPOSE_PROFILES=authentik         # Enable only Authentik
-# COMPOSE_PROFILES=ollama            # Enable only Ollama
-# COMPOSE_PROFILES=traefik-bundled   # Enable bundled Traefik reverse proxy
+# Enable optional services via profiles. Combine multiple profiles with commas.
+#
+# Available profiles:
+#   - database:  PostgreSQL database (disable to use external database)
+#   - cache:     Valkey cache (disable to use external Redis)
+#   - openbao:   OpenBao secrets management (disable to use external vault or fallback encryption)
+#   - authentik: Authentik OIDC authentication (disable to use external auth provider)
+#   - ollama:    Ollama AI/LLM service (disable to use external LLM service)
+#   - traefik-bundled: Bundled Traefik reverse proxy (disable to use external proxy)
+#   - full:      Enable all optional services (turnkey deployment)
+#
+# Examples:
+# COMPOSE_PROFILES=full                        # Everything bundled (development)
+# COMPOSE_PROFILES=database,cache,openbao      # Core services only
+# COMPOSE_PROFILES=                            # All external services (production)
+COMPOSE_PROFILES=full
 
 # ======================
 # Traefik Reverse Proxy