luckberg/unraid-docker-manager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(13-01): overhaul README with architecture, configuration, and troubleshooting sections

Browse Source 
- 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
2026-02-08 18:27:31 -05:00
parent 70115f7cd6
commit 6cdb9581a1
1 changed files with 138 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+138 -12
View File
@@ -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. 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 ### 2. Create Telegram API Credential
In the n8n web interface: In the n8n web interface:
@@ -66,8 +62,6 @@ In the n8n web interface:
3. Name: `Telegram API` 3. Name: `Telegram API`
4. Access Token: paste your bot token from @BotFather (same token used in step 1) 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 ### 3. Import Workflows
The bot uses 8 workflows total (1 main + 7 sub-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 3. Import all 8 files in any order
4. When prompted, map the `Telegram API` credential 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 ### 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. 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 6. Repeat for **IF Callback Authenticated** node
7. Save the workflow 7. Save the workflow
### 5. Activate Workflow ### 5. Activate Workflows
1. Click the "Active" toggle in the top-right corner of the main workflow 1. Click the "Active" toggle in the top-right corner of the **main workflow**
2. Test by sending "status" to your bot in Telegram 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 ## Usage
### Text Commands
Send commands via Telegram or use the persistent menu buttons: Send commands via Telegram or use the persistent menu buttons:
| Command | Description | | 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`. 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 ### Menu Buttons
Send `/start` or any unrecognized text to display the persistent keyboard with quick-access buttons for all commands. 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 ## Security
The bot only responds to the Telegram user ID configured in the IF nodes. Messages from other users are silently ignored. The bot only responds to the Telegram user ID configured in the IF nodes. Messages from other users are silently ignored.