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

```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