unraid-docker-manager/README.md

# 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.

### 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)

### 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

### 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 Workflows

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 [ARCHITECTURE.md](ARCHITECTURE.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 |
|---------|-------------|
| `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`.

### 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 [ARCHITECTURE.md](ARCHITECTURE.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.

## License

MIT