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.

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.

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.

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