mirror of
https://github.com/kossakovsky/n8n-install.git
synced 2026-03-07 22:33:11 +00:00
Remove CLAUDE.md documentation file to streamline project resources. This deletion eliminates outdated guidance related to the n8n-installer, contributing to a more efficient and maintainable codebase.
This commit is contained in:
Yury Kossakovsky
162
CLAUDE.md
162
CLAUDE.md
@@ -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
|
||||
Reference in New Issue
Block a user