unraid-docker-manager/DEPLOYMENT_GUIDE.md

Deployment Guide - Plan 10-05

Overview

This guide covers deploying the modularized workflow structure with 3 sub-workflows:

• Container Update (existing)
• Container Actions (existing)
• Container Logs (NEW)

Current Status

• Main workflow: 209 → 199 nodes (-10 nodes, -4.8%)
• Sub-workflows: 3 total
• Node count above target (120-150) but significantly improved

Deployment Steps

1. Import Container Logs Sub-workflow

# Import n8n-container-logs.json to n8n
# Via UI: Settings → Import → Select n8n-container-logs.json
# Or via n8n CLI if available

After import, note the workflow ID assigned by n8n.

2. Update Main Workflow with Logs Sub-workflow ID

# Edit n8n-workflow.json
# Find "Execute Text Logs" and "Execute Inline Logs" nodes
# Update their workflowId.value to the actual ID from step 1

# Example:
# "workflowId": {
#   "__rl": true,
#   "mode": "list",
#   "value": "ACTUAL_ID_HERE"
# }

Or use this script:

import json
import sys

if len(sys.argv) < 2:
    print("Usage: python update_logs_id.py <logs_workflow_id>")
    sys.exit(1)

logs_id = sys.argv[1]

with open('n8n-workflow.json', 'r') as f:
    workflow = json.load(f)

# Update Execute Text Logs
for node in workflow['nodes']:
    if node['name'] in ['Execute Text Logs', 'Execute Inline Logs']:
        node['parameters']['workflowId']['value'] = logs_id
        print(f"Updated {node['name']} to use {logs_id}")

with open('n8n-workflow.json', 'w') as f:
    json.dump(workflow, f, indent=2)

print("✓ Updated main workflow with logs sub-workflow ID")

3. Import/Update Main Workflow

# Import updated n8n-workflow.json to n8n
# This will update the existing main workflow

4. Verify Sub-workflows are Active

In n8n UI, ensure all 3 sub-workflows are set to "Active":

• Container Update
• Container Actions
• Container Logs

5. Test All Paths

Text Commands:

# Test to bot
status
start plex
stop plex
restart plex
update plex
logs plex
logs plex 100

Inline Keyboard:

1. Send "status" to get container list
2. Click on a container
3. Test buttons:
   • Start/Stop/Restart
   • Update
   • Logs
   • Back to List

Batch Operations:

1. Send "status" to get container list
2. Enable batch mode (toggle button)
3. Select multiple containers
4. Click "Start Selected" / "Stop Selected" / "Restart Selected"
5. Verify progress messages update
6. Verify final summary

Batch Update:

1. Send command: update all
2. Confirm the update
3. Verify progress messages
4. Verify all containers updated

Verification Checklist

• Container Logs sub-workflow imported and active
• Main workflow updated with correct logs workflow ID
• All sub-workflows marked as Active in n8n
• Text commands work (status, start, stop, restart, update, logs)
• Inline keyboard flows work (all buttons functional)
• Batch selection and execution works
• Batch update all works with progress tracking
• Error messages display correctly
• No Docker API errors in n8n logs

Architecture

Main Workflow (n8n-workflow.json) - 199 nodes
├── Telegram Trigger + Auth
├── Command Parsing & Routing
├── Container List & Status Display
├── Batch Selection UI
├── Confirmation Dialogs
└── Sub-workflow Orchestration
    ├── Container Update (7AvTzLtKXM2hZTio92_mC)
    │   └── Used by: Execute Text Update, Execute Callback Update, Execute Batch Update
    ├── Container Actions (fYSZS5PkH0VSEaT5)
    │   └── Used by: Execute Container Action, Execute Inline Action,
    │       Execute Confirmed Stop Action, Execute Batch Action Sub-workflow
    └── Container Logs (NEW - get ID after import)
        └── Used by: Execute Text Logs, Execute Inline Logs

Sub-workflow Input Contracts

Container Update

{
  "containerId": "string",
  "containerName": "string",
  "chatId": "number",
  "messageId": "number",
  "responseMode": "text|inline"
}

Container Actions

{
  "containerId": "string",
  "containerName": "string",
  "action": "start|stop|restart",
  "chatId": "number",
  "messageId": "number",
  "responseMode": "text|inline"
}

Container Logs

{
  "containerId": "string (optional if containerName provided)",
  "containerName": "string",
  "lineCount": "number (default 50, max 1000)",
  "chatId": "number",
  "messageId": "number",
  "responseMode": "text|inline"
}

Troubleshooting

"Workflow not found" errors

• Verify sub-workflow IDs in main workflow match actual IDs in n8n
• Ensure sub-workflows are set to Active

Batch operations not working

• Check that "Prepare Batch Update/Action Input" nodes have correct logic
• Verify Execute Batch Update/Action nodes use correct workflow IDs
• Check "Handle Batch Update/Action Result Sub" processes results correctly

Logs not displaying

• Verify Container Logs workflow ID is correct in main workflow
• Check Docker socket proxy is accessible from n8n
• Verify container names are being normalized correctly

Future Optimization Opportunities

The current node count (199) is above the target range (120-150). Additional optimization could include:

1. Consolidate batch confirmation flows (~15 nodes)

   • "Build Batch Commands" path (old execute-all-at-once batch)
   • Could be refactored to use the same loop-based approach

2. Streamline UI/keyboard generation (~20 nodes)

   • Many "Build *" and "Format *" nodes for keyboards
   • Could use shared helper sub-workflow

3. Combine similar routers (~5-10 nodes)

   • Multiple IF/Switch nodes for similar logic
   • Could be consolidated

Total potential reduction: ~40-45 nodes → target of ~155-160 nodes

However, these optimizations require deeper refactoring and testing. The current state achieves the primary goals:

• ✓ No duplicate update logic (single + batch use same sub-workflow)
• ✓ No duplicate action logic (single + batch use same sub-workflow)
• ✓ No duplicate logs logic (text + inline use same sub-workflow)
• ✓ All container operations modularized
• ✓ Easier maintenance and debugging

Notes

• The main workflow still contains batch selection UI, which is intentionally kept in main workflow for better user experience
• Confirmation dialogs remain inline for simplicity
• The old "Build Batch Commands" flow (execute-all-at-once) is separate from the new progress-loop batch execution
• Both batch approaches coexist for backward compatibility