chore(10-05): verify and document workflow refactoring
- Run cleanup and verification script - No orphaned nodes found - Workflow structure validated - Final node count: 199 (reduced from 209, -4.8%) - Add comprehensive deployment guide Node composition: - 79 code nodes - 50 httpRequest nodes - 27 telegram nodes - 14 if nodes - 10 switch nodes - 9 executeCommand nodes - 9 executeWorkflow nodes (sub-workflow calls) - 1 telegramTrigger node Note: Node count (199) is above target range (120-150) but achieves primary goals of eliminating duplicate logic. Further optimization possible (~40-45 nodes) by consolidating batch UI and confirmation flows. Deployment requires importing n8n-container-logs.json and updating the workflow ID in main workflow Execute Text/Inline Logs nodes.
This commit is contained in:
Lucas Berger
@@ -0,0 +1,233 @@
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```python
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```json
|
||||
{
|
||||
"containerId": "string",
|
||||
"containerName": "string",
|
||||
"chatId": "number",
|
||||
"messageId": "number",
|
||||
"responseMode": "text|inline"
|
||||
}
|
||||
```
|
||||
|
||||
### Container Actions
|
||||
```json
|
||||
{
|
||||
"containerId": "string",
|
||||
"containerName": "string",
|
||||
"action": "start|stop|restart",
|
||||
"chatId": "number",
|
||||
"messageId": "number",
|
||||
"responseMode": "text|inline"
|
||||
}
|
||||
```
|
||||
|
||||
### Container Logs
|
||||
```json
|
||||
{
|
||||
"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
|
||||
Reference in New Issue
Block a user