From 545ebac064f5cd28f970aedf274d2191da204a03 Mon Sep 17 00:00:00 2001 From: Yury Kossakovsky Date: Wed, 27 Aug 2025 12:41:38 -0600 Subject: [PATCH] Add CLAUDE.md to provide comprehensive guidance for the n8n-installer project, detailing installation steps, service management, architecture, and security considerations. --- CLAUDE.md | 162 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 162 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..aa4a771 --- /dev/null +++ b/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 \ No newline at end of file