Add CLAUDE.md to provide comprehensive guidance for the n8n-installer project, detailing installation steps, service management, architecture, and security considerations.

CLAUDE.md

@@ -0,0 +1,162 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is the n8n-installer: a Docker Compose-based installer that creates a comprehensive self-hosted AI automation environment. It includes n8n, Flowise, Open WebUI, Supabase, Qdrant, Langfuse, Ollama, and 20+ other services that can be selectively deployed.
+
+## Essential Commands
+
+### Installation and Updates
+```bash
+# Main installation (from project root)
+sudo bash ./scripts/install.sh
+
+# Update all services to latest versions
+sudo bash ./scripts/update.sh
+
+# Clean up unused Docker resources
+sudo bash ./scripts/docker_cleanup.sh
+```
+
+### Docker Operations
+```bash
+# View running services
+docker compose ps
+
+# View logs for specific service
+docker compose logs [service-name]
+
+# Restart services with specific profiles
+docker compose --profile n8n,flowise up -d
+
+# Stop all services
+docker compose down
+```
+
+### Python Helper Script
+```bash
+# Start services with automatic profile detection
+python3 start_services.py
+```
+
+### Service Management
+```bash
+# Apply configuration updates to running services
+sudo bash ./scripts/apply_update.sh
+
+# View all available Docker Compose profiles
+grep -E '^\s*profiles:' docker-compose.yml
+
+# Check service health status
+docker compose ps --format "table {{.Name}}\t{{.Status}}\t{{.Ports}}"
+```
+
+## Architecture
+
+### Core Installation Flow
+The installation follows a strict 6-step sequence managed by `scripts/install.sh`:
+1. **01_system_preparation.sh** - Updates system, installs dependencies, configures security
+2. **02_install_docker.sh** - Installs Docker Engine and Docker Compose
+3. **03_generate_secrets.sh** - Creates .env file with secure passwords and keys
+4. **04_wizard.sh** - Interactive service selection with whiptail UI
+5. **05_run_services.sh** - Deploys selected services using Docker Compose profiles
+6. **06_final_report.sh** - Displays access URLs and credentials
+
+### Docker Compose Architecture
+- **Profiles**: Services are organized into profiles (n8n, flowise, monitoring, langfuse, ollama, etc.)
+- **Environment**: All configuration through `.env` file generated in step 3
+- **Volumes**: Named volumes for data persistence across container rebuilds
+- **Networks**: All services on default Docker network with internal service discovery
+
+### Key Service Dependencies
+- **n8n**: Requires postgres, redis. Runs in queue mode with configurable worker count
+- **Supabase**: Full stack with postgres, auth, storage, analytics, edge functions
+- **Langfuse**: Requires postgres, redis, clickhouse, minio for LLM observability
+- **Open WebUI**: Can integrate with Ollama for local LLMs
+
+## Important Implementation Details
+
+### Environment Variable System
+- Generated by `03_generate_secrets.sh` using `openssl rand -hex`
+- Contains service hostnames, passwords, API keys
+- Used by both Docker Compose and Caddy for routing
+
+### Service Selection Wizard
+- `04_wizard.sh` uses whiptail to create interactive checklist
+- Updates `COMPOSE_PROFILES` in `.env` based on user selections
+- Some services have dependencies (e.g., langfuse requires clickhouse)
+
+### Shared File Access
+- `./shared/` directory is mounted to `/data/shared` inside n8n containers
+- Use this path in n8n workflows to read/write files on the host system
+
+### Custom n8n Configuration
+- Pre-installs Node.js libraries: cheerio, axios, moment, lodash
+- Runs in production mode with PostgreSQL backend
+- Enables queue mode for parallel workflow processing with configurable worker count
+- Community packages and AI runners enabled
+- Configured for tool usage and external function calls
+- Metrics enabled for monitoring integration
+
+### Network Architecture
+- Caddy handles HTTPS/TLS termination and reverse proxy
+- Services exposed via subdomains: n8n.domain.com, flowise.domain.com, grafana.domain.com, etc.
+- Internal services (redis, postgres) not exposed externally
+- Supports Cloudflare Tunnel as alternative to port exposure
+
+## Common Development Tasks
+
+### Testing Profile Changes
+1. Update `COMPOSE_PROFILES` in `.env`
+2. Run `docker compose --profile [profiles] up -d`
+3. Check `docker compose ps` to verify services started
+
+### Adding New Services
+1. Define service in `docker-compose.yml` with appropriate profile
+2. Add hostname variables to Caddy environment section
+3. Update `04_wizard.sh` to include in service selection
+4. Add Caddyfile routing if service needs web access
+5. Consider service dependencies and health checks
+
+### Backup/Restore Workflows
+- n8n workflows stored in `./n8n/backup/workflows/`
+- Credentials stored in `./n8n/backup/credentials/`
+- Import script: `./n8n/n8n_import_script.sh`
+
+### Troubleshooting Service Issues
+1. Check service logs: `docker compose logs [service-name]`
+2. Verify environment variables in `.env`
+3. Check DNS configuration for domain-based services
+4. Monitor resource usage: `docker stats`
+
+## Security Considerations
+
+- All services require authentication (configured during setup)
+- Firewall configured to only allow SSH, HTTP, HTTPS
+- Fail2Ban enabled for brute-force protection
+- SSL certificates managed by Caddy with Let's Encrypt
+- Sensitive data in `.env` file (never commit to git)
+
+## File Structure Notes
+- `memory-bank/` - Project documentation and development notes
+- `flowise/` - Flowise workflow templates and custom tools
+- `n8n-tool-workflows/` - n8n workflow tools for integration
+- `grafana/` - Monitoring dashboards and provisioning configs
+- `scripts/` - Installation and utility scripts (all bash)
+- `prometheus/` - Prometheus monitoring configuration
+- `searxng/` - SearXNG search engine settings
+- `caddy-addon/` - Additional Caddy configuration files
+- `python-runner/` - Optional Python execution environment
+
+## Critical Implementation Notes
+
+- Never modify the installation script sequence (01-06) without understanding dependencies
+- Always use logging functions from `utils.sh` in new scripts
+- The `.env` file contains all secrets and must never be committed
+- Services use Docker health checks - respect dependency conditions
+- Profile-based deployment allows selective service activation
+- All bash scripts should be executable and follow the established patterns
+- When modifying `docker-compose.yml`, maintain the x-templates pattern for service definitions
+- Community workflows are imported during installation - see `n8n/backup/workflows/` for examples