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)
• Your Telegram User ID (from @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:

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:

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

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.

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