# 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