Lucas Berger
e6e5df8754
- 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)
139 lines
4.8 KiB
Markdown
139 lines
4.8 KiB
Markdown
# Docker Manager Bot
|
|
|
|
Telegram bot for managing Docker containers on Unraid. Control containers from your phone with simple keyword commands.
|
|
|
|
## Prerequisites
|
|
|
|
- Unraid server with Docker enabled
|
|
- n8n container running on Unraid
|
|
- Telegram Bot Token (from [@BotFather](https://t.me/botfather))
|
|
- Your Telegram User ID (from [@userinfobot](https://t.me/userinfobot))
|
|
|
|
## Installation
|
|
|
|
### 1. Configure Docker Environment
|
|
|
|
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 \
|
|
--network dockernet \
|
|
-v /path/to/curl:/usr/bin/curl:ro \
|
|
-e TELEGRAM_BOT_TOKEN=your_bot_token_here \
|
|
-p 5678:5678 \
|
|
n8nio/n8n
|
|
```
|
|
|
|
**Required configuration:**
|
|
|
|
- `--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:
|
|
|
|
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 (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):
|
|
|
|
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)
|
|
|
|
2. In n8n: Workflows > Import from File
|
|
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.
|
|
|
|
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 of the main workflow
|
|
2. Test by sending "status" to your bot in Telegram
|
|
|
|
## Usage
|
|
|
|
Send commands via Telegram or use the persistent menu buttons:
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `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.
|
|
|
|
## Security
|
|
|
|
The bot only responds to the Telegram user ID configured in the IF nodes. Messages from other users are silently ignored.
|
|
|
|
## License
|
|
|
|
MIT
|