Initial skills documentation — 25 categories, all SKILL.md + references + scripts

2026-07-15 17:42:20 -04:00
commit 1b4fcd4427
976 changed files with 188344 additions and 0 deletions
@@ -0,0 +1,73 @@
+# Caddy Subdomain Routing Pattern
+
+## When to Use Subdomains vs Path-Based Routing
+
+**Subdomains** (`n8n.itpropartner.com`) are preferred when:
+- The backend app uses absolute asset paths (`/assets/foo.js`, `/static/bar.css`)
+- The app has its own SPA router that doesn't support base-path rewriting
+- You need WebSocket support for real-time features
+- The app redirects internally (signin flows, OAuth callbacks)
+
+**Path-based** (`app1.itpropartner.com/n8n/`) only works when:
+- The app supports `BASE_PATH` or equivalent configuration
+- All internal asset references are relative or use the base path
+- You've verified the SPA router handles the sub-path correctly
+
+## Subdomain Caddyfile Pattern
+
+```caddy
+n8n.itpropartner.com {
+    reverse_proxy 127.0.0.1:5678 {
+        flush_interval -1
+    }
+}
+```
+
+`flush_interval -1` enables WebSocket support — required for n8n's real-time editor.
+
+## Let's Encrypt Pitfalls
+
+### Rate Limit: Too Many Failed Authorizations
+
+If DNS isn't pointing to the server when cert issuance is attempted, failed validations count against a 5-per-hour-per-domain rate limit. After 5 failures, Let's Encrypt blocks further attempts for 1 hour. 
+
+**Fix:** Ensure DNS A record resolves to the correct IP BEFORE adding the domain to Caddyfile. Caddy auto-requests certs on config load.
+
+### Staging vs Production Certs
+
+Caddy tries staging first, then production. A staging cert issuance success does NOT mean the production cert will work — they have separate rate limits.
+
+### Retry After Rate Limit
+
+Caddy auto-retries when the limit resets. Check with:
+```bash
+journalctl -u caddy --no-pager -n 20 | grep -E "cert|rateLimit|will retry"
+```
+
+## n8n-Specific Configuration
+
+### Docker Volume Permissions
+
+When migrating n8n Docker volumes between servers, the `n8n_data` volume must be owned by UID 1000 (the `node` user inside the container):
+```bash
+chown -R 1000:1000 /var/lib/docker/volumes/n8n_n8n_data/_data
+```
+Failure to do this causes `EACCES: permission denied, open '/home/node/.n8n/crash.journal'`.
+
+### N8N_PROTOCOL Behind Reverse Proxy
+
+Set `N8N_PROTOCOL=http` when behind Caddy — Caddy handles SSL termination. Setting it to `https` inside forces n8n to do its own SSL redirects, creating redirect loops.
+
+### N8N_HOST
+
+Must match the public domain — `n8n.itpropartner.com`. n8n uses this for OAuth callbacks and webhook URLs.
+
+### Migration Steps
+
+1. Stop old containers: `docker compose down`
+2. Tar volumes: `tar czf n8n-data.tar.gz -C /var/lib/docker/volumes n8n_postgres_data n8n_n8n_data`
+3. SCP to new server
+4. Extract, create volumes, restore data
+5. Fix permissions on `n8n_data` volume
+6. Update `.env` with new `N8N_HOST` and `N8N_PROTOCOL=http`
+7. `docker compose up -d`