# 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