Skip to content

n8n — Runbook

Routine Tasks

Trigger a workflow reimport

Push any change under services/n8n/ or ansible/playbooks/n8n.yml to main. Or trigger the workflow manually from Forgejo Actions.

Rotate the webhook token

  1. Generate a new token and update Vault: vault kv patch secret/homelab-sso n8n_webhook_token=<new>
  2. Trigger the Deploy Glance workflow to push the new value to Glance
  3. Update the Header Auth credential in the n8n UI: Credentials → find Glance Webhook Token → edit value
  4. Save and re-activate both webhook nodes

Logs

Log Contents Location Loki label Format Example query
n8n application Workflow executions, webhook events, errors, startup Docker (LXC 120) stdout job="automation", container="n8n" Plain text {job="automation", container="n8n"} \|= "error"

Notes: - n8n logs are NOT JSON — do not use | json pipeline - SSH fallback: ssh [email protected] "pct exec 120 -- docker logs n8n"

Troubleshooting

Workflow not activating after deploy

n8n workflows are imported but may need to be manually activated on first deploy if the activation state isn't persisted. Go to the n8n UI → Workflows → toggle the workflow active.

Webhook returns 404

  • Verify the workflow is active (toggle in n8n UI)
  • Check the webhook URL path matches the workflow's trigger node
  • Check n8n logs for errors

Bookmark webhook returns 401

  1. Verify the token in the iOS Shortcut matches secret/n8n → n8n_webhook_token
  2. Check the Authorization: Bearer <token> header is being sent correctly
  3. If token was rotated, update the Shortcuts on all devices

Bookmark not appearing in Karakeep

  1. Check n8n execution logs for the Archive Page workflow
  2. Verify KARAKEEP_API_KEY is set: check /opt/n8n/.env on LXC 120
  3. Test Karakeep API directly: curl -s -H "Authorization: Bearer $KARAKEEP_API_KEY" http://192.168.1.217:3000/api/v1/bookmarks

ArchiveBox not receiving URLs

  1. Check n8n execution logs for the POST to ArchiveBox node
  2. Verify ARCHIVEBOX_API_KEY is set in /opt/n8n/.env
  3. Test ArchiveBox API directly: curl -s -H "Authorization: Bearer $ARCHIVEBOX_API_KEY" http://192.168.1.128:8000/api/v1/core/snapshots
  4. If ArchiveBox returns 403/404 on /api/v1/cli/add, the version may not support the REST API — check with docker exec archivebox archivebox version

Reddit archiving fails

  1. Reddit rate limits: 10 req/min unauthenticated. Check if you're hitting the limit
  2. Reddit .json endpoint may return 429 — check n8n execution logs for HTTP status
  3. Verify User-Agent header is being sent (Reddit blocks requests without one)

Fallback chain not triggering

  1. The karakeep-crawled workflow must be active in n8n
  2. Karakeep must be configured to send webhooks to http://192.168.1.120:5678/webhook/karakeep-crawled after crawl
  3. Check Karakeep webhook settings in the Karakeep admin UI

ntfy alerts not arriving

  1. Verify ntfy is running on LXC 119: {container_name="ntfy"}
  2. Check the NTFY_URL env var in n8n points to http://192.168.1.119:8093
  3. Subscribe to the archival topic in the ntfy app to receive alerts