309 lines
6.9 KiB
Markdown
309 lines
6.9 KiB
Markdown
# 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
|