claude-home/productivity/n8n/README.md

# n8n Workflow Automation - Quick Reference

Self-hosted n8n instance at **https://n8n.manticorum.com/**

## Quick Links

- **Web UI:** https://n8n.manticorum.com/
- **Documentation:** [CONTEXT.md](CONTEXT.md) - Complete technical documentation
- **Troubleshooting:** [troubleshooting.md](troubleshooting.md) - Common issues and solutions
- **Examples:** [examples/](examples/) - Configuration templates

## At a Glance

| Property | Value |
|----------|-------|
| **URL** | https://n8n.manticorum.com/ |
| **Internal IP** | 10.10.0.210 |
| **Container** | LXC 210 (docker-n8n-lxc) |
| **Resources** | 4 CPU, 8GB RAM, 128GB disk |
| **Database** | PostgreSQL 15 |
| **Deployment** | 2025-11-13 |

## Quick Commands

```bash
# SSH into n8n host
ssh -i ~/.ssh/homelab_rsa root@10.10.0.210

# View logs
ssh root@10.10.0.210 "cd /opt/n8n && docker compose logs -f n8n"

# Restart n8n
ssh root@10.10.0.210 "cd /opt/n8n && docker compose restart n8n"

# Backup database
ssh root@10.10.0.210 "cd /opt/n8n && docker compose exec -T postgres pg_dump -U n8n n8n > /root/n8n-backup-\$(date +%Y%m%d).sql"

# Update to latest version
ssh root@10.10.0.210 "cd /opt/n8n && docker compose pull && docker compose up -d"

# Check status
ssh root@10.10.0.210 "cd /opt/n8n && docker compose ps"
```

## File Locations

| Path | Description |
|------|-------------|
| `/opt/n8n/docker-compose.yml` | Container configuration |
| `/opt/n8n/.env` | Environment variables and secrets |
| `n8n_data` volume | Workflows, credentials, settings |
| `n8n_postgres_data` volume | PostgreSQL database |

## Access Credentials

**Location:** `/opt/n8n/.env` on LXC 210

View current credentials:
```bash
ssh root@10.10.0.210 "cat /opt/n8n/.env | grep BASIC_AUTH"
```

## Common Tasks

### Create a New Workflow
1. Login to https://n8n.manticorum.com/
2. Click "Add workflow"
3. Add nodes by clicking "+"
4. Connect nodes by dragging
5. Test with "Execute Workflow"
6. Activate with toggle switch

### Setup a Webhook
1. Add "Webhook" node to workflow
2. Choose HTTP Method (GET, POST, etc.)
3. Set Path (e.g., `my-webhook`)
4. Activate workflow
5. Use URL: `https://n8n.manticorum.com/webhook/my-webhook`

### Backup Workflows
```bash
# Backup database (includes all workflows and credentials)
ssh root@10.10.0.210 "cd /opt/n8n && docker compose exec -T postgres pg_dump -U n8n n8n" > n8n-backup.sql

# Download locally
scp -i ~/.ssh/homelab_rsa root@10.10.0.210:/root/n8n-backup-*.sql ~/backups/n8n/
```

### View Execution History
1. Login to n8n UI
2. Click "Executions" in top nav
3. Filter by workflow, status, or date
4. Click execution to view details

## Architecture

```
Internet
  ↓
Nginx Proxy Manager (NPM)
  ↓ HTTPS/SSL
https://n8n.manticorum.com
  ↓ HTTP (internal)
LXC 210 (10.10.0.210:5678)
  ├─ n8n Container
  │  └─ Workflow Engine
  └─ PostgreSQL Container
     └─ Database (workflows, credentials, history)
```

## Integration Examples

### Discord Notifications
1. Webhook node → Discord Webhook URL
2. Message node → Format notification
3. Trigger: Manual, Schedule, or Webhook

### Homelab Monitoring
1. HTTP Request → Check service health
2. IF node → Check response code
3. Discord/Email → Send alert if down
4. Schedule Trigger → Run every 5 minutes

### Automated Backups
1. Execute Command → Run backup script
2. HTTP Request → Upload to cloud storage
3. Discord → Send completion notification
4. Schedule Trigger → Daily at 2 AM

### API Data Collection
1. HTTP Request → Fetch data from API
2. Set node → Transform data
3. PostgreSQL → Store in database
4. Schedule Trigger → Hourly

## Security Best Practices

- ✅ Basic authentication enabled
- ✅ HTTPS via NPM with Let's Encrypt
- ✅ Internal network only (no direct internet exposure)
- ✅ Credentials encrypted with N8N_ENCRYPTION_KEY
- ⚠️ Never share encryption key
- ⚠️ Regularly rotate admin password
- ⚠️ Review workflow permissions

## Troubleshooting Quick Checks

| Issue | Quick Check |
|-------|-------------|
| Can't access n8n.manticorum.com | `curl http://10.10.0.210:5678` |
| Login fails | Check `.env` file for correct credentials |
| Webhook not working | Verify workflow is **Active** (green toggle) |
| Slow performance | `ssh root@10.10.0.210 "docker stats n8n"` |
| Database errors | `ssh root@10.10.0.210 "docker compose logs postgres"` |

See [troubleshooting.md](troubleshooting.md) for detailed solutions.

## Resources

- **Official Docs:** https://docs.n8n.io/
- **Community Forum:** https://community.n8n.io/
- **Workflow Templates:** https://n8n.io/workflows/
- **Discord:** https://discord.gg/n8n

## Maintenance Schedule

**Weekly:**
- Review failed executions
- Check disk space
- Monitor container health

**Monthly:**
- Backup database
- Update n8n version
- Clean up old execution data
- Review and archive unused workflows

**Quarterly:**
- Test disaster recovery
- Audit credentials
- Review webhook security
- Performance optimization

## Support

For issues or questions:
1. Check [troubleshooting.md](troubleshooting.md)
2. Review [CONTEXT.md](CONTEXT.md) for configuration details
3. Search n8n community forum
4. Check n8n documentation

---

**Last Updated:** 2025-11-13
**Deployed By:** Claude Code automation
**Maintained By:** Cal Corum