docs(12-01): update environment and architecture documentation

- Update README to document docker-socket-proxy architecture instead of direct socket mount - Clarify TELEGRAM_BOT_TOKEN needs both n8n credential AND env var - Clarify user ID is hardcoded in IF nodes (no env var needed) - Add missing commands to usage table (update all, /list) - Document all 8 workflow files (main + 7 sub-workflows) - Mark ENV-01, ENV-02, DEBT-01, DEBT-02 as complete in REQUIREMENTS.md - Verify DEBT-02 is fixed (single --max-time 600 flag, no duplicates)
2026-02-08 17:14:15 -05:00
parent 1ef726942a
commit e6e5df8754
2 changed files with 73 additions and 28 deletions
@@ -62,13 +62,13 @@

 ### Environment & Config

- [ ] **ENV-01**: Documentation clarifies TELEGRAM_USERID env var necessity (required vs hardcoded)
- [ ] **ENV-02**: Documentation clarifies TELEGRAM_BOT_TOKEN env var necessity (env var vs n8n credential)
+- ✓ **ENV-01**: Documentation clarifies TELEGRAM_USERID env var necessity (required vs hardcoded) — Phase 12
+- ✓ **ENV-02**: Documentation clarifies TELEGRAM_BOT_TOKEN env var necessity (env var vs n8n credential) — Phase 12

 ### Technical Debt

- [ ] **DEBT-01**: README documents proxy architecture (not direct docker.sock mounting)
- [ ] **DEBT-02**: Fix duplicate --max-time flags in image pull command
+- ✓ **DEBT-01**: README documents proxy architecture (not direct docker.sock mounting) — Phase 12
+- ✓ **DEBT-02**: Fix duplicate --max-time flags in image pull command — Verified fixed (single --max-time 600, no duplicates), Phase 12
 - [ ] **DEBT-03**: Consolidate duplicated update flow between single and batch paths

 ## v2+ Requirements (Deferred)
@@ -103,10 +103,10 @@
 | BATCH-06 | Phase 11 | Pending |
 | BATCH-07 | Phase 11 | Pending |
 | UNR-01 | Phase 12 | Pending |
-| ENV-01 | Phase 12 | Pending |
-| ENV-02 | Phase 12 | Pending |
-| DEBT-02 | Phase 12 | Pending |
-| DEBT-01 | Phase 13 | Pending |
+| ENV-01 | Phase 12 | Complete |
+| ENV-02 | Phase 12 | Complete |
+| DEBT-02 | Phase 12 | Complete |
+| DEBT-01 | Phase 12 | Complete |

 **Coverage:**
 - v1.2 requirements: 12 total
@@ -11,28 +11,52 @@ Telegram bot for managing Docker containers on Unraid. Control containers from y

 ## Installation

-### 1. Configure n8n Container
+### 1. Configure Docker Environment

-Your n8n container needs Docker socket access to manage other containers. Add these flags to your n8n container configuration:
+The bot requires two containers to operate securely:
+
+#### docker-socket-proxy
+
+For security, n8n accesses Docker via a filtering proxy instead of mounting the socket directly. Deploy [docker-socket-proxy](https://github.com/Tecnativa/docker-socket-proxy):
+
+```bash
+docker run -d \
+  --name docker-socket-proxy \
+  --network dockernet \
+  -v /var/run/docker.sock:/var/run/docker.sock:ro \
+  -e CONTAINERS=1 \
+  -e POST=1 \
+  tecnativa/docker-socket-proxy
+```
+
+This proxy blocks dangerous operations (exec, build, commit) while allowing container management.
+
+#### n8n
+
+Your n8n container needs access to the proxy and a static curl binary:

 ```bash
 docker run -d \
  --name n8n \
-  --group-add 281 \
-  -v /var/run/docker.sock:/var/run/docker.sock \
+  --network dockernet \
  -v /path/to/curl:/usr/bin/curl:ro \
+  -e TELEGRAM_BOT_TOKEN=your_bot_token_here \
  -p 5678:5678 \
  n8nio/n8n
 ```

-**Required flags:**
+**Required configuration:**

- `--group-add 281` - Adds Docker group (GID 281 on Unraid) so n8n can access the Docker socket
- `-v /var/run/docker.sock:/var/run/docker.sock` - Mounts the Docker socket for container management
+- `--network dockernet` - Connects to the docker-socket-proxy container
 - `-v /path/to/curl:/usr/bin/curl:ro` - Mounts a static curl binary (hardened n8n image lacks package manager)
+- `-e TELEGRAM_BOT_TOKEN=your_bot_token_here` - Required for HTTP Request nodes that send Telegram messages

 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:
@@ -40,29 +64,47 @@ In the n8n web interface:
 1. Go to Settings > Credentials > Add Credential
 2. Search for "Telegram API"
 3. Name: `Telegram API`
-4. Access Token: paste your bot token from @BotFather
+4. Access Token: paste your bot token from @BotFather (same token used in step 1)

-### 3. Import Workflow
+**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):
+
+1. Download all workflow files from this repository:
+   - `n8n-workflow.json` (main workflow)
+   - `n8n-update.json` (container updates)
+   - `n8n-actions.json` (start/stop/restart)
+   - `n8n-logs.json` (log retrieval)
+   - `n8n-batch-ui.json` (batch selection UI)
+   - `n8n-status.json` (container list/status)
+   - `n8n-confirmation.json` (confirmation dialogs)
+   - `n8n-matching.json` (container name matching)

-1. Download `n8n-workflow.json` from this repository
 2. In n8n: Workflows > Import from File
-3. Select `n8n-workflow.json`
+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. To set it:
+The workflow only responds to your Telegram user ID. **No environment variable is used** — the user ID is hardcoded in the workflow nodes.

-1. Open the imported workflow
-2. Find the **IF User Authenticated** node
-3. Click to edit, find the condition with `rightValue`
-4. Change `563878771` to your Telegram user ID
-5. Repeat for **IF Callback Authenticated** node
-6. Save the workflow
+To set your user ID:
+
+1. Get your Telegram user ID from [@userinfobot](https://t.me/userinfobot)
+2. Open the main workflow (`n8n-workflow.json`)
+3. Find the **IF User Authenticated** node
+4. Click to edit, find the condition with `rightValue`
+5. Change `563878771` to your Telegram user ID
+6. Repeat for **IF Callback Authenticated** node
+7. Save the workflow

 ### 5. Activate Workflow

-1. Click the "Active" toggle in the top-right corner
+1. Click the "Active" toggle in the top-right corner of the main workflow
 2. Test by sending "status" to your bot in Telegram

 ## Usage
@@ -71,15 +113,18 @@ Send commands via Telegram or use the persistent menu buttons:

 | Command | Description |
 |---------|-------------|
-| `status` | View all containers with status indicators |
+| `status` or `/list` | View all containers with status indicators |
 | `start <name>` | Start a stopped container |
 | `stop <name>` | Stop a running container |
 | `restart <name>` | Restart a container |
 | `update <name>` | Pull latest image and recreate container |
+| `update all` | Update all containers with :latest tag |
 | `logs <name> [lines]` | View container logs (default: 50 lines) |

 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).
+
 ### Menu Buttons

 Send `/start` or any unrecognized text to display the persistent keyboard with quick-access buttons for all commands.