diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index a7241a8..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,162 +0,0 @@ -# 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. **06_run_services.sh** - Deploys selected services using Docker Compose profiles -6. **07_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