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)
This commit is contained in:
Lucas Berger
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user