Auto-sync: 20260105-122831
This commit is contained in:
Hutson
308
N8N.md
Normal file
308
N8N.md
Normal file
@@ -0,0 +1,308 @@
|
||||
# n8n - Workflow Automation
|
||||
|
||||
n8n is an extendable workflow automation tool deployed on docker-host2 for automating tasks across your homelab and external services.
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Setting | Value |
|
||||
|---------|-------|
|
||||
| **URL** | https://n8n.htsn.io |
|
||||
| **Local IP** | 10.10.10.207:5678 |
|
||||
| **Server** | docker-host2 (PVE2 VMID 302) |
|
||||
| **Database** | PostgreSQL (containerized) |
|
||||
| **API Endpoint** | http://10.10.10.207:5678/api/v1/ |
|
||||
|
||||
---
|
||||
|
||||
## Claude Code Integration (MCP)
|
||||
|
||||
### n8n-MCP Server
|
||||
|
||||
The n8n-MCP server gives Claude Code deep knowledge of all 545+ n8n nodes, enabling it to build complete workflows from natural language descriptions.
|
||||
|
||||
**Installation:** Already configured in `~/Library/Application Support/Claude/claude_desktop_config.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"n8n-nodes": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@czlonkowski/n8n-mcp"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**What This Enables:**
|
||||
- ✅ Build n8n workflows from natural language
|
||||
- ✅ Get detailed help with node parameters and options
|
||||
- ✅ Best practices for n8n node usage
|
||||
- ✅ Debug workflow issues with full node context
|
||||
|
||||
**Example Prompts:**
|
||||
```
|
||||
"Create an n8n workflow to monitor Prometheus and send Telegram alerts"
|
||||
"Build a workflow that triggers when Syncthing has errors"
|
||||
"What's the best n8n node to parse JSON responses?"
|
||||
```
|
||||
|
||||
**How It Works:**
|
||||
- MCP server provides offline documentation for all n8n nodes
|
||||
- No connection to your n8n instance required
|
||||
- Claude builds workflows that you can then import into https://n8n.htsn.io
|
||||
|
||||
**Resources:**
|
||||
- [n8n-MCP GitHub](https://github.com/czlonkowski/n8n-mcp)
|
||||
- [MCP Documentation](https://docs.n8n.io/advanced-ai/accessing-n8n-mcp-server/)
|
||||
|
||||
---
|
||||
|
||||
## API Access
|
||||
|
||||
### API Key
|
||||
|
||||
```
|
||||
X-N8N-API-KEY: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI3NTdiMDA5YS1hMjM2LTQ5MzUtODkwNS0xZDY1MjYzZWE2OWYiLCJpc3MiOiJuOG4iLCJhdWQiOiJwdWJsaWMtYXBpIiwiaWF0IjoxNzY2ODEwMzA3fQ.RIZAbpDa7LiUPWk48qOscJ9-d9gRAA0afMDX_V3oSVo
|
||||
```
|
||||
|
||||
### API Examples
|
||||
|
||||
**List Workflows:**
|
||||
```bash
|
||||
curl -H "X-N8N-API-KEY: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI3NTdiMDA5YS1hMjM2LTQ5MzUtODkwNS0xZDY1MjYzZWE2OWYiLCJpc3MiOiJuOG4iLCJhdWQiOiJwdWJsaWMtYXBpIiwiaWF0IjoxNzY2ODEwMzA3fQ.RIZAbpDa7LiUPWk48qOscJ9-d9gRAA0afMDX_V3oSVo" \
|
||||
http://10.10.10.207:5678/api/v1/workflows
|
||||
```
|
||||
|
||||
**Get Workflow by ID:**
|
||||
```bash
|
||||
curl -H "X-N8N-API-KEY: YOUR_API_KEY" \
|
||||
http://10.10.10.207:5678/api/v1/workflows/{id}
|
||||
```
|
||||
|
||||
**Trigger Workflow:**
|
||||
```bash
|
||||
curl -X POST \
|
||||
-H "X-N8N-API-KEY: YOUR_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"data": {"key": "value"}}' \
|
||||
http://10.10.10.207:5678/api/v1/workflows/{id}/execute
|
||||
```
|
||||
|
||||
**API Documentation:** https://docs.n8n.io/api/
|
||||
|
||||
---
|
||||
|
||||
## Deployment Details
|
||||
|
||||
### Docker Compose
|
||||
|
||||
**Location:** `/opt/n8n/docker-compose.yml` on docker-host2
|
||||
|
||||
**Services:**
|
||||
- `n8n` - Main application (port 5678)
|
||||
- `postgres` - Database backend
|
||||
|
||||
**Volumes:**
|
||||
- `n8n_data` - Workflow data, credentials, settings
|
||||
- `postgres_data` - Database storage
|
||||
|
||||
### Environment Configuration
|
||||
|
||||
```yaml
|
||||
N8N_HOST: n8n.htsn.io
|
||||
N8N_PORT: 5678
|
||||
N8N_PROTOCOL: https
|
||||
NODE_ENV: production
|
||||
WEBHOOK_URL: https://n8n.htsn.io/
|
||||
GENERIC_TIMEZONE: America/Los_Angeles
|
||||
DB_TYPE: postgresdb
|
||||
DB_POSTGRESDB_HOST: postgres
|
||||
DB_POSTGRESDB_DATABASE: n8n
|
||||
DB_POSTGRESDB_USER: n8n
|
||||
DB_POSTGRESDB_PASSWORD: n8n_secure_password_2024
|
||||
```
|
||||
|
||||
### Resource Limits
|
||||
|
||||
- **Memory**: 512MB-1GB (soft/hard)
|
||||
- **CPU**: Shared (4 vCPUs on host)
|
||||
|
||||
---
|
||||
|
||||
## Common Tasks
|
||||
|
||||
### Restart n8n
|
||||
|
||||
```bash
|
||||
ssh docker-host2 'cd /opt/n8n && docker compose restart n8n'
|
||||
```
|
||||
|
||||
### View Logs
|
||||
|
||||
```bash
|
||||
ssh docker-host2 'docker logs -f n8n'
|
||||
```
|
||||
|
||||
### Backup Workflows
|
||||
|
||||
Workflows are stored in PostgreSQL. To backup:
|
||||
|
||||
```bash
|
||||
ssh docker-host2 'docker exec n8n-postgres pg_dump -U n8n n8n > /tmp/n8n-backup-$(date +%Y%m%d).sql'
|
||||
```
|
||||
|
||||
### Update n8n
|
||||
|
||||
```bash
|
||||
ssh docker-host2 'cd /opt/n8n && docker compose pull n8n && docker compose up -d n8n'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Traefik Configuration
|
||||
|
||||
**File:** `/etc/traefik/conf.d/n8n.yaml` on CT 202
|
||||
|
||||
```yaml
|
||||
http:
|
||||
routers:
|
||||
n8n-secure:
|
||||
entryPoints:
|
||||
- websecure
|
||||
rule: "Host(`n8n.htsn.io`)"
|
||||
service: n8n
|
||||
tls:
|
||||
certResolver: cloudflare
|
||||
priority: 50
|
||||
|
||||
n8n-redirect:
|
||||
entryPoints:
|
||||
- web
|
||||
rule: "Host(`n8n.htsn.io`)"
|
||||
middlewares:
|
||||
- n8n-https-redirect
|
||||
service: n8n
|
||||
priority: 50
|
||||
|
||||
services:
|
||||
n8n:
|
||||
loadBalancer:
|
||||
servers:
|
||||
- url: "http://10.10.10.207:5678"
|
||||
|
||||
middlewares:
|
||||
n8n-https-redirect:
|
||||
redirectScheme:
|
||||
scheme: https
|
||||
permanent: true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Monitoring
|
||||
|
||||
### Prometheus
|
||||
|
||||
n8n exposes metrics at `http://10.10.10.207:5678/metrics` (if enabled)
|
||||
|
||||
### Grafana
|
||||
|
||||
n8n metrics can be visualized in Grafana dashboards
|
||||
|
||||
### Uptime Monitoring
|
||||
|
||||
Add to Pulse: https://pulse.htsn.io
|
||||
- Monitor: https://n8n.htsn.io
|
||||
- Check interval: 60s
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### n8n won't start
|
||||
|
||||
```bash
|
||||
ssh docker-host2 'docker logs n8n | tail -50'
|
||||
ssh docker-host2 'docker logs n8n-postgres | tail -50'
|
||||
```
|
||||
|
||||
### Database connection issues
|
||||
|
||||
```bash
|
||||
# Check postgres health
|
||||
ssh docker-host2 'docker exec n8n-postgres pg_isready -U n8n'
|
||||
|
||||
# Restart postgres
|
||||
ssh docker-host2 'cd /opt/n8n && docker compose restart postgres'
|
||||
```
|
||||
|
||||
### SSL/HTTPS issues
|
||||
|
||||
```bash
|
||||
# Check Traefik config
|
||||
ssh root@10.10.10.250 'cat /etc/traefik/conf.d/n8n.yaml'
|
||||
|
||||
# Reload Traefik
|
||||
ssh root@10.10.10.250 'systemctl reload traefik'
|
||||
```
|
||||
|
||||
### API not responding
|
||||
|
||||
```bash
|
||||
# Test API locally
|
||||
curl -H "X-N8N-API-KEY: YOUR_KEY" http://10.10.10.207:5678/api/v1/workflows
|
||||
|
||||
# Check if n8n container is healthy
|
||||
ssh docker-host2 'docker ps | grep n8n'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration Examples
|
||||
|
||||
### Homelab Automation Ideas
|
||||
|
||||
1. **Backup Notifications** - Send Telegram alerts when backups complete
|
||||
2. **Server Monitoring** - Query Prometheus and alert on high CPU/memory
|
||||
3. **Media Management** - Trigger Sonarr/Radarr downloads
|
||||
4. **Home Assistant Integration** - Automate smart home workflows
|
||||
5. **Git Webhooks** - Deploy changes from Gitea automatically
|
||||
6. **Syncthing Monitoring** - Alert when sync folders get behind
|
||||
7. **UPS Alerts** - Notify on power events from NUT
|
||||
|
||||
---
|
||||
|
||||
## Security Notes
|
||||
|
||||
- API key provides full access to all workflows and data
|
||||
- Store API key securely (added to this doc for homelab reference)
|
||||
- n8n credentials are encrypted at rest in PostgreSQL
|
||||
- HTTPS enforced via Traefik
|
||||
- No public internet exposure (only via Tailscale)
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
**New to n8n?** Start here: **[N8N-INTEGRATIONS.md](N8N-INTEGRATIONS.md)** ⭐
|
||||
|
||||
This guide includes:
|
||||
- ✅ Network access verification
|
||||
- ✅ Credential setup for all homelab services
|
||||
- ✅ 10 ready-to-use starter workflows
|
||||
- ✅ Home Assistant, Prometheus, Syncthing, Telegram integrations
|
||||
- ✅ Troubleshooting tips
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [n8n Homelab Integrations Guide](N8N-INTEGRATIONS.md) - **START HERE**
|
||||
- [docker-host2 VM details](VMS.md)
|
||||
- [Traefik reverse proxy](TRAEFIK.md)
|
||||
- [IP Assignments](IP-ASSIGNMENTS.md)
|
||||
- [Pulse Setup](PULSE-SETUP.md)
|
||||
|
||||
**Last Updated:** 2025-12-26
|
||||
Reference in New Issue
Block a user