From 6cdb9581a13535aa2a0cec1bfb0debd44381b007 Mon Sep 17 00:00:00 2001 From: Lucas Berger Date: Sun, 8 Feb 2026 18:27:31 -0500 Subject: [PATCH] docs(13-01): overhaul README with architecture, configuration, and troubleshooting sections - Add dedicated Architecture section with ASCII diagram (main workflow + 7 sub-workflows) - Add dedicated Configuration section (separated from installation steps) - Add dedicated Troubleshooting section (5 common issues with fixes) - Document batch selection workflow (toggle checkmarks, multi-select UI) - Document inline keyboard Update All button location and usage - Expand Usage section with inline keyboard and batch operations subsections - Document infrastructure container exclusion from batch updates - Link to DEPLOY-SUBWORKFLOWS.md for technical details - Remove outdated DEPLOYMENT_GUIDE.md reference - Expand from 139 to 264 lines (comprehensive, not over-documented) --- README.md | 150 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 138 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 1fc4d92..42b1b63 100644 --- a/README.md +++ b/README.md @@ -53,10 +53,6 @@ docker run -d \ If using Unraid's Community Applications, add these to the "Extra Parameters" and "Path" sections of your n8n container template. -**Note:** The TELEGRAM_BOT_TOKEN environment variable is used by HTTP Request nodes. The bot token must also be configured as an n8n credential (see step 2). - -For detailed docker-socket-proxy setup and security configuration, see [DEPLOYMENT_GUIDE.md](DEPLOYMENT_GUIDE.md). - ### 2. Create Telegram API Credential In the n8n web interface: @@ -66,8 +62,6 @@ In the n8n web interface: 3. Name: `Telegram API` 4. Access Token: paste your bot token from @BotFather (same token used in step 1) -**Why both credential and environment variable?** The Telegram Trigger node uses the n8n credential. HTTP Request nodes that send messages use `$env.TELEGRAM_BOT_TOKEN`. Both are required. - ### 3. Import Workflows The bot uses 8 workflows total (1 main + 7 sub-workflows): @@ -86,8 +80,6 @@ The bot uses 8 workflows total (1 main + 7 sub-workflows): 3. Import all 8 files in any order 4. When prompted, map the `Telegram API` credential -For detailed sub-workflow architecture, see [DEPLOY-SUBWORKFLOWS.md](DEPLOY-SUBWORKFLOWS.md). - ### 4. Configure Your User ID The workflow only responds to your Telegram user ID. **No environment variable is used** — the user ID is hardcoded in the workflow nodes. @@ -102,13 +94,71 @@ To set your user ID: 6. Repeat for **IF Callback Authenticated** node 7. Save the workflow -### 5. Activate Workflow +### 5. Activate Workflows -1. Click the "Active" toggle in the top-right corner of the main workflow -2. Test by sending "status" to your bot in Telegram +1. Click the "Active" toggle in the top-right corner of the **main workflow** +2. Verify all 7 sub-workflows are also set to "Active" +3. Test by sending "status" to your bot in Telegram + +## Architecture + +The bot follows a modular architecture with 8 n8n workflows: + +``` +Telegram User + ↓ +Main Workflow (166 nodes) +├── Authentication & routing +├── Command parsing +└── Sub-workflow orchestration + ├→ Container Update (34 nodes) + ├→ Container Actions (11 nodes) + ├→ Container Logs (9 nodes) + ├→ Batch UI (16 nodes) + ├→ Container Status (11 nodes) + ├→ Confirmation Dialogs (16 nodes) + └→ Container Matching (23 nodes) + ↓ +docker-socket-proxy + ↓ +Docker Engine +``` + +The main workflow handles authentication and routing, while domain-specific logic lives in sub-workflows. This modular design simplifies debugging and isolates container operations. + +For detailed sub-workflow contracts and technical architecture, see [DEPLOY-SUBWORKFLOWS.md](DEPLOY-SUBWORKFLOWS.md). + +## Configuration + +### Environment Variables + +**TELEGRAM_BOT_TOKEN** (required): +- Set as n8n environment variable: `-e TELEGRAM_BOT_TOKEN=your_token` +- Also configure as n8n credential (Settings > Credentials > Telegram API) +- **Why both?** The Telegram Trigger node uses the credential. HTTP Request nodes use the environment variable. + +### User Authentication + +The bot only responds to your Telegram user ID. **There is no environment variable for user ID** — it is hardcoded in two workflow nodes: + +1. **IF User Authenticated** (text message auth) +2. **IF Callback Authenticated** (inline button auth) + +To change the authorized user, edit these nodes and update the `rightValue` field (default: `563878771`). + +### Docker Socket Proxy + +The docker-socket-proxy container must have these environment variables: + +- `CONTAINERS=1` - Allows container list/inspect/start/stop operations +- `POST=1` - Allows container creation and updates + +All dangerous operations (exec, build, commit, swarm management) are blocked by default. ## Usage +### Text Commands + Send commands via Telegram or use the persistent menu buttons: | Command | Description | @@ -123,12 +173,88 @@ Send commands via Telegram or use the persistent menu buttons: Container names support partial matching. For example, `start plex` will match `linuxserver-plex`. -**Interactive keyboard:** Use `/status` to access the interactive container list with action buttons. Click any container to view details and perform actions (start, stop, restart, update, logs). +### Inline Keyboard + +Use `/status` to access the interactive container list: + +1. **Container list** - Shows 6 containers per page with pagination +2. **Click any container** - Opens action menu (start/stop/restart/update/logs) +3. **Batch selection** - Click "Batch" button to enter multi-select mode + - Toggle containers on/off (checkmarks show selection) + - "Stop Selected" or "Restart Selected" performs batch operations +4. **Update All** - The "Update All :latest" button updates all containers with :latest tag + +### Batch Operations + +**Text command:** +``` +update all +``` +Sends a confirmation message, then updates all containers with :latest tags. Shows progress for each container. + +**Inline keyboard:** +1. Send `/status` +2. Click "Batch" button +3. Toggle containers on/off using checkmark buttons +4. Click "Stop Selected" / "Restart Selected" / "Update All :latest" +5. Confirm the operation +6. Watch progress messages for each container + +**Note:** Infrastructure containers (n8n, docker-socket-proxy) are excluded from batch updates to prevent bot self-destruction. ### Menu Buttons Send `/start` or any unrecognized text to display the persistent keyboard with quick-access buttons for all commands. +## Troubleshooting + +### "Workflow not found" errors + +**Cause:** Sub-workflow IDs don't match, or sub-workflows are inactive. + +**Fix:** +1. Open n8n and verify all 7 sub-workflows are imported +2. Click each sub-workflow and set to "Active" +3. Check Execute Workflow nodes in main workflow have correct IDs + +### "Cannot connect to Docker" + +**Cause:** docker-socket-proxy is not running or not on the same network as n8n. + +**Fix:** +1. Run `docker ps | grep socket-proxy` to verify it's running +2. Check both containers are on the same Docker network: `docker inspect n8n | grep NetworkMode` +3. Restart docker-socket-proxy and n8n containers + +### Bot not responding + +**Cause:** Main workflow is inactive or Telegram credential is misconfigured. + +**Fix:** +1. Open main workflow in n8n and click "Active" toggle +2. Check Settings > Credentials > Telegram API has correct bot token +3. Verify `TELEGRAM_BOT_TOKEN` environment variable is set in n8n container +4. Send a test message to your bot (check for auth errors in n8n execution log) + +### Unraid shows "apply update" badge after bot update + +**Expected behavior:** After the bot updates a container, Unraid's Docker tab may show an "apply update" badge. + +**Why:** The bot uses Docker API directly. Unraid manages containers through its XML template system and doesn't track external updates. + +**Fix:** Click "Apply Update" in Unraid's Docker tab. It completes instantly because the image is already pulled — Unraid just recreates the container to sync its tracking. + +For more details, see Known Limitations in [DEPLOY-SUBWORKFLOWS.md](DEPLOY-SUBWORKFLOWS.md). + +### Batch operations not working + +**Cause:** Not all 8 workflows are imported and active. + +**Fix:** +1. Verify all 8 workflow files imported (main + 7 sub-workflows) +2. Check each sub-workflow is set to "Active" +3. Test with a simple batch: `/status` → "Batch" → select 1 container → "Stop Selected" + ## Security The bot only responds to the Telegram user ID configured in the IF nodes. Messages from other users are silently ignored.