DockerDiscordControl

KO | EN

gitlite — search

#javascript #ai #typescript #android #machine-learning #deep-learning #linux #macos #nodejs #java #windows #cli #mcp #open-source

DockerDiscordControl

(★ 11)

A powerful Discord bot and web interface to manage Docker containers remotely. This application bridges the gap between Discord and your Docker environment, allowing container monitoring and control directly through Discord channels.

DockerDiscordControl Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# DockerDiscordControl v2.3.1 🐳

[![Version](https://img.shields.io/badge/Version-v2.3.1-brightgreen?style=for-the-badge)](https://github.com/DockerDiscordControl/DockerDiscordControl/releases/tag/v2.3.1) [![Python](https://img.shields.io/badge/Python-3.14-blue?style=for-the-badge)](https://python.org) [![Base Image](https://img.shields.io/badge/Base-Alpine%203.24-blueviolet?style=for-the-badge)](https://raw.githubusercontent.com/DockerDiscordControl/DockerDiscordControl/main/) [![Tests](https://img.shields.io/badge/Tests-3480%2F3480-success?style=for-the-badge)](https://raw.githubusercontent.com/DockerDiscordControl/DockerDiscordControl/main/) [![Coverage](https://img.shields.io/badge/Coverage-86%25-brightgreen?style=for-the-badge)](https://raw.githubusercontent.com/DockerDiscordControl/DockerDiscordControl/main/) [![Docker Pulls](https://img.shields.io/docker/pulls/dockerdiscordcontrol/dockerdiscordcontrol?style=for-the-badge)](https://hub.docker.com/r/dockerdiscordcontrol/dockerdiscordcontrol) [![Unraid](https://img.shields.io/badge/Unraid-Community%20Apps-orange?style=for-the-badge)](https://raw.githubusercontent.com/DockerDiscordControl/DockerDiscordControl/main/docs/UNRAID.md) [![Wiki](https://img.shields.io/badge/Documentation-Wiki-lightgrey?style=for-the-badge)](https://github.com/DockerDiscordControl/DockerDiscordControl/wiki)

**Homepage:** [https://ddc.bot](https://ddc.bot) | **[Complete Documentation](../../wiki)**

Control your Docker containers directly from Discord! This application provides a Discord bot and a web interface to manage Docker containers (start, stop, restart, view status) with a focus on stability, security, and performance. The default image is an ultra-optimized Alpine Linux build with the latest security patches and enhanced performance.

## 🆕 Latest Updates

### ✅ **v2.3.1 (2026-08-08) - Security Patch**

🔒 **Dependency security fix**
- Bumped **cryptography → 50.0.0** to resolve **CVE-2026-69247** (GHSA-g6cj-pr64-35w5): a Bleichenbacher timing/error oracle in PKCS#7 `EnvelopedData` decryption (High severity).
- No functional changes — dependency-only patch release across all platform images.

### ✅ **v2.3.0 (2026-07-01) - Live Game-Server Player Counts**

Show **live player counts** for your game servers right in the Discord status overview (e.g. `Valheim  3/8`).

**New: per-container player-count feature**
- Live "players online / max" for game servers via the [opengsq](https://github.com/opengsq/opengsq-python) library — shown compactly behind the server name in the community status overview (`Name  3/8`) and in the per-container control box (`│ Players: 3/8`).
- **4 protocols:** Source / A2S (most Steam games — Valheim, Enshrouded, V Rising, Icarus, Rust, CS, Project Zomboid, …), **Minecraft**, **Satisfactory** (app token) and **Palworld** (REST admin password).
- **Automatic detection:** DDC probes each online container across all its published ports (transport-aware ordering), auto-detects Source vs Minecraft, and unlocks the per-server "Players" toggle only for servers that actually answer — with a 15-minute probe window, permanent verdicts, and a manual **"Test now"** re-check for slow-booting servers.
- **Guided setup:** the container name/image suggests the right protocol, and token games (Satisfactory / Palworld) make the Info button glow until a credential is entered.
- Fully **non-blocking & best-effort** — a dead or slow game server never affects or delays the Discord status loop.
- **Localized in all 40 supported languages.**

🔒 **Quality:** built and hardened across **three independent multi-agent code reviews**; **+102 unit tests**; validated live against real game servers.

### ✅ **v2.2.4 (2026-06-30) - Alpine 3.24 / Python 3.14 Base Bump**

🐳 **Updated runtime base**
- Base image bumped **Alpine 3.23.3 → 3.24** (**Python 3.12 → 3.14**)
- Fixes the bundled-OpenSSL-independent **SQLite** advisories CVE-2026-11822 / CVE-2026-11824 (`sqlite-libs` 3.51.2 → 3.53.2, FTS5 memory corruption)
- `gevent` bumped **25.5.1 → 25.9.1** for Python 3.14 wheel compatibility
- Validated with a full soak test against a live Discord server before release: bot connects, fetches containers, posts overviews, all v2.2.3 fixes work — zero runtime errors on 3.14

> **Note:** the Alpine `busybox` advisory CVE-2025-60876 (Medium) has no upstream fix in any branch yet and remains until Alpine ships a patched package — `apk upgrade` (already in the Dockerfile) will pick it up automatically on a future rebuild.

### ✅ **v2.2.3 (2026-06-29) - Overview Reliability & Dependency Security**

🐛 **No more duplicate overview messages**
- Long-lived overviews (edited in place) older than 30 days were skipped by the age-limited cleanup, so a regeneration could post a fresh overview on top of the stale one — now the tracked overview is deleted by its known message ID first
- Concurrent posters (inactivity regeneration, event recreate, recovery, `/ss`, `/control`, initial send, channel hot-reload/teardown) are serialized by a per-channel lock with re-validation, so two paths can never produce a duplicate
- Overview message IDs are persisted and restored on restart (atomic `mech_state.json` writes), so a restart deletes the previous overview by ID instead of orphaning it

✨ **Overview re-posts below the bot's own messages**
- The "move overview to the bottom" feature now also triggers when the bot's *own* notifications (restart/update-watcher triggers) bury the overview — previously only foreign messages counted. The managed overview is never treated as foreign, so in-place editing is untouched
- Regeneration is skipped while a user is mid-interaction (e.g. expanding the mech)

🔒 **Dependencies**
- `cryptography>=48.0.1` (GHSA-537c-gmf6-5ccf — vulnerable OpenSSL bundled in wheels `< 48.0.1`)

> **Upgrade note:** on the first restart after this version, `mech_state.json` does not yet contain the new `channel_overview_message_ids` key, so a pre-existing >30-day overview may survive that first regeneration once. It is removed automatically on the next cycle (self-healing); thereafter the persisted ID prevents duplicates across restarts.

### ✅ **v2.2.2 (2026-04-26) - Hardening, Performance & Test-Suite Sanitization**

🔒 **Security Hardening**
- New `/logout` endpoint clears session and forces Basic-Auth re-prompt
- Session idle-timeout (default 30 min, override via `DDC_SESSION_IDLE_TIMEOUT`)
- SSRF whitelist on Translation API: only DeepL Pro/Free, Google, Microsoft endpoints accepted
- Setup-phase rate-limit (5 req/min) protects the bootstrap window
- 12-char password policy with complexity (only enforced on `/setup` — existing passwords unaffected)
- `SESSION_COOKIE_SAMESITE=Strict` (was `Lax`)
- CSRF foundation via Flask-WTF (all blueprints currently exempted; infrastructure ready)
- Alpine base image pinned to multi-arch digest (`@sha256:25109184…`)

⚡ **Performance & RAM**
- Locale lazy-loading: ~5 MB → ~120 KB initial RAM (en pre-loaded, others on-demand)
- Animation disk cache LRU eviction at 200 MB (`DDC_ANIM_DISK_LIMIT_MB`)
- Waitress thread pool now CPU-aware (`DDC_WAITRESS_THREADS`, default min(4, cpu_count, 8))
- Request-scoped config caching (eliminates repeated disk reads per page render)
- 8 dataclasses with `slots=True` for memory efficiency

🧹 **Architecture / Bug Fixes**
- gevent monkey-patching is now opt-in (`DDC_ENABLE_GEVENT=1`); standard waitress runtime uses plain threading and no longer fights asyncio
- Scheduler service: hosted/standalone modes (auto-detected) — eliminates "Cannot start scheduler service in existing event loop" warning
- `import docker.errors` explicit (fixes silent `AttributeError` on docker daemon errors)
- `pytz.UnknownTimeZoneError` properly caught with UTC fallback
- `_debug_mode_lock` upgraded to `RLock` (re-entry safety)
- `DDC_CONFIG_DIR`, `DDC_PROGRESS_DATA_DIR`, `DDC_METRICS_DIR` env-var support for custom config layouts

📋 **Logging & Storage**
- `discord.log` rotation (10 MB × 5 backups), `bot_error.log` (5 MB × 3), `user_actions.log` (5 MB × 3) — bounded growth
- Debug-Mode-Toggle UI now shows restart-required hint
- Stripped misleading `[DEBUG INIT]` / `[SETUP DEBUG]` prefixes from INFO logs

✅ **Testing**
- 3353 tests pass single-pass in container (was 184 with 48 failing pre-v2.2.2)
- Coverage 86% (was 27% at v2.2.2 release; +59pp from post-release coverage push)
- 5 new test directories added in v2.2.2: security, performance, storage, infrastructure, i18n
- 4 production bugs uncovered + fixed via test sanitization
- Suite pollution fixes: `sys.modules` mutations and `importlib.reload` leaks in fixtures eliminated

⚠️ **Breaking Changes** (rare edge cases)
- Translation API: self-hosted DeepL/LibreTranslate endpoints are now blocked. Set `deepl_api_url` to one of the four whitelisted hosts.
- `SESSION_COOKIE_SAMESITE=Strict`: Web UI embedded in cross-site iframes (e.g. some dashboard tools) may lose session; use same eTLD+1 or open directly.
- Idle session timeout 30 min default — override with `DDC_SESSION_IDLE_TIMEOUT=<seconds>` if you want longer (or shorter, floor 60s).

🆕 **New Environment Variables**
| Variable | Default | Purpose |
|---|---|---|
| `DDC_ENABLE_GEVENT` | unset (off) | Re-enable gevent monkey-patching for legacy gunicorn workers |
| `DDC_SESSION_IDLE_TIMEOUT` | `1800` | Session idle timeout in seconds (floor 60) |
| `DDC_WAITRESS_THREADS` | auto | Web UI thread pool size (2..16) |
| `DDC_ANIM_DISK_LIMIT_MB` | `200` | Animation disk cache cap; 0 disables eviction |
| `DDC_CONFIG_DIR` | `/app/config` | Override config directory (testing/custom layouts) |
| `DDC_PROGRESS_DATA_DIR` | (auto) | Override mech progress data directory |
| `DDC_METRICS_DIR` | (auto) | Override performance metrics directory |

---

### ✅ **v2.2.1 (2026-03-27) - Full Internationalization (40 Languages)**

🌍 **New Feature: Multi-Language Support (i18n)**
- **40 languages** for both Web UI and Discord Bot, independently selectable
- Web UI Language dropdown with instant switch (no save needed, auto-reloads)
- Bot Language dropdown for Discord bot messages
- All 40 languages fully translated (1457 keys each): English, German, French, Spanish, Portuguese (BR/PT), Italian, Dutch, Polish, Czech, Slovak, Romanian, Hungarian, Bulgarian, Croatian, Greek, Turkish, Russian, Ukrainian, Arabic, Hebrew, Persian, Hindi, Thai, Vietnamese, Indonesian, Malay, Japanese, Korean, Chinese (Simplified/Traditional), Swedish, Norwegian, Danish, Finnish, Estonian, Latvian, Lithuanian, Slovenian, Serbian
- RTL support for Arabic, Hebrew, and Persian
- JSON-based translation system (1457 keys per language)
- Translation Manager rewritten from 2541-line inline dict to modular JSON loader

🐛 **Bug Fixes:**
- Fixed double save button click causing infinite spinner (duplicate onclick + addEventListener)
- Fixed channel translation losing embed preview images (link previews from Steam, YouTube, etc. now preserved in translated messages)
- Fixed channel translation duplicating text when embed descriptions repeat message content
- "Requires restart" badge now only shows when the value has actually been changed
- Fixed duplicate "Configuration saved" notification on page reload

---

### ✅ **v2.2.0 (2026-03-26) - Channel Translation & Hot-Reload**

✨ **New Feature: Channel Translation**
- Automatically translate Discord messages between channels using DeepL, Google Translate, or Microsoft Translator
- Multiple source→target channel pairs with per-pair configuration
- Text, embeds, images, and videos are forwarded with translations
- Videos are re-uploaded as real Discord files for proper video player display
- YouTube, Twitter/X, Twitch, Reddit, Vimeo URLs get auto-previewed in translations
- Encrypted API key storage (independent of password, survives password changes)
- Rate limiting, retry logic, and auto-disable after consecutive failures
- Loop prevention (3 layers: bot message check, translated ID tracking, target channel exclusion)
- Configurable via Web UI: provider selection, test translation, toggle Original link & provider footer
- Web UI Advanced Settings: rate limit, max text length, show/hide Original link & footer

✨ **New Feature: Channel Hot-Reload**
- Adding or removing channels in the Web UI takes effect immediately — no container restart needed
- Bot automatically detects config changes, sets up new channels, and tears down removed ones
- "Requires restart" badge on Bot Token and Guild ID fields (the only settings that still need a restart)

🐛 **Bug Fixes:**
- Fixed channel form parser skipping channels after deleted rows (numbering gap caused data loss)
- Fixed JS row numbering creating duplicate field names after channel deletion
- Fixed non-numeric channel IDs bypassing parser validation
- Fixed Web UI console errors: `ReferenceError: rawLogsCache` (JS scoping), log auto-refresh using hardcoded URLs
- Fixed race condition in translation encryption key creation (double-checked locking + atomic write)

🔒 **Security:**
- Bumped `requests` to >=2.33.0 (CVE-2026-25645)

---

### ✅ **v2.1.9 (2026-03-21) - Critical Channel Save Fix**

🐛 **Critical Bug Fix:**
- **Jinja2 Scoping Bug** (Root Cause of Issue #14): Fixed `{% set %}` variable inside `{% for %}` loop not surviving outer scope in Jinja2 templates. This caused the empty default channel row to ALWAYS render alongside existing channels, creating duplicate form fields. When saved, Flask received lists instead of strings for channel IDs, corrupting the data and causing all existing channels to be deleted. Fixed using Jinja2 `namespace()` objects.

🐛 **Additional Bug Fixes:**
- **Channel Delete Button**: Fixed delete button not working for existing channel rows in the web UI. The click handler was only attached to dynamically added rows, not template rendered ones. Fixed via event delegation.

📝 **Improvements:**
- **Port Diagnostics**: Cleaned up false "PORT ISSUES DETECTED" warnings when port mapping detection is unavailable from inside the container. Now only warns when the port is genuinely not listening.

---

### ✅ **v2.1.8 (2026-03-21) - Channel Config & Startup Fixes**

🐛 **Bug Fixes:**
- **Admin Channel Persistence** (Issue #14): Fixed channels not being saved/loaded correctly after restart
  - Added fallback chain for channel loading: individual files → config.json → channels_config.json (legacy)
  - Auto-migration from legacy `channels_config.json` to individual channel files
  - Safe save order: new channel files are saved BEFORE old ones are deleted (prevents data loss)
  - Added safety check preventing deletion of all channels if saves fail
  - Reduced config.json writes from N+2 to 1 per save cycle (SMB/NFS stability)
- **Startup Port Diagnostics**: Removed false "Port 9374 NOT LISTENING" warning during startup (diagnostics ran before Waitress was ready)
- **Config Cache Staleness**: Bot now uses `force_reload=True` when loading config at startup to avoid stale cached data

📝 **Improvements:**
- Enhanced diagnostic logging for channel save/load operations
- Channel save return values are now checked and logged

---

### ✅ **v2.1.7 (2026-03-20) - Security Patch**

🔒 **Security Fixes:**
- **CVE-2026-32767** (Critical 9.8): Updated `expat` to 2.7.5-r0 — fixes XML parsing vulnerability
- **CVE-2026-32777, CVE-2026-32776** (Medium): Additional expat security patches
- **CVE-2026-32778** (Low): Expat minor security fix
- **CVE-2025-60876** (Medium): Busybox wget HTTP header injection mitigated (wget removed)

---

### ✅ **v2.1.6 (2026-03-08) - Bugfixes & Story Service**

🐛 **Bug Fixes:**
- **Donation Restore**: Fixed toggle-count pattern across all three layers (delete, rebuild, list/stats) — restoring deleted donations now works correctly
- **Mech Story Reading**: Added missing `get_all_chapters()` and `get_chapter_key_for_level()` methods to MechStoryService — "Geschichte lesen" button no longer crashes

---

### ✅ **v2.1.5 (2026-03-08) - Security Hardening & Stability**

🔒 **Security Hardening:**
- **Dependencies**: Flask 3.1.3, Werkzeug 3.1.6, cryptography 46.0.5, Pillow 12.1.1, gevent 25.5.1
- **Path Traversal Protection**: Regex whitelist + resolve() boundary checks on all file-based services
- **XSS Prevention**: HTML escaping in config-ui, auto-actions, and toast notifications
- **Auth Hardening**: Tasks blueprint now requires login, setup credentials removed from error responses
- **PBKDF2 Iterations**: Standardized to 600,000 across all password hashing
- **Docker Hardening**: `no-new-privileges` + health check in docker-compose
- **Alpine 3.23.3**: Updated base image in both builder and runtime stages
- **CVE-2025-60876**: Removed busybox wget applet (HTTP header injection)

✨ **Improvements:**
- **Config Save Protection**: Automatic backup before every save, critical field preservation (bot_token, guild_id)
- **Targeted Config Updates**: New `update_config_fields()` prevents accidental data loss during partial saves
- **Setup Auto-Login**: Automatic redirect and authentication after first-time password setup
- **Docker Connectivity**: Replaced async check with synchronous Docker SDK (fixes gevent/asyncio conflict)
- **CI**: Test matrix updated to Python 3.10, 3.11, 3.12 (dropped EOL 3.9)

---

### ✅ **v2.1.4 (2025-01-20) - Security & Mech Evolution**

🔒 **Security Fixes:**
- **Werkzeug**: Upgrade to 3.1.5 - Fix for GHSA-hgf8-39gv-g3f2 (safe_join Windows special device names)

✨ **New Features:**
- **Mech Evolution 10**: New rest animation frames for level 10
- **Cache-Only Mode**: Improved handling when PNG sources are not available

---

### ✅ **v2.1.3 (2025-12-06) - Security Updates**

🔒 **Security Fixes:**
- **urllib3**: Upgrade to 2.6.0 - Fix for GHSA-s4qh-5xfq-xqjg (Authorization header exposure on redirect)
- **Werkzeug**: Upgrade to 3.1.4

✨ **Improvements:**
- **AAS Messages**: Preserve Auto-Action System messages during channel cleanup
- **UI**: Handwritten channel hints + /task reference fixes
- **Mobile**: Improved spacing and responsive fixes for Web UI

---

### ✅ **v2.1.2 (2025-11-28) - Unraid/NAS Permission Fix**

🔧 **Unraid & NAS Compatibility:**
- **FIXED:** Container failed to start on Unraid due to volume permission issues
- **NEW:** PUID/PGID environment variables for custom user/group mapping
- **NEW:** Automatic permission fixing at container startup
- **IMPROVED:** Clear error messages with Unraid-specific guidance

📦 **For Unraid Users:**
```yaml
environment:
  - PUID=99
  - PGID=100
```

🎮 **New Discord Command:**
- **NEW:** `/addadmin` - Add admin users directly from Discord
  - Opens modal to enter Discord User ID
  - In Control channels: Any user can add admins
  - In Status channels: Only existing admins can add new admins

---

### ✅ **v2.1.1 (2025-11-27) - Hot-Reload & Bug Fixes**

🔥 **Hot-Reload Configuration:**
- **NEW:** Most settings now take effect immediately without container restart
- **HOT-RELOAD:** Container selection, order, display names, actions
- **HOT-RELOAD:** Channel permissions and admin users list
- **HOT-RELOAD:** Web UI password, language, and timezone
- **REQUIRES RESTART:** Only Bot Token and Guild ID changes

🔒 **Security & Permissions:**
- **IMPROVED:** Strict channel separation - `/ss` only in status channels, `/control` only in control channels
- **FIXED:** Missing permission check for `/control` command

🐛 **Bug Fixes:**
- **FIXED:** Channel config files saved with name instead of Discord ID
- **FIXED:** UpdateNotifier wrong method name
- **FIXED:** ConfigService missing attribute error
- **IMPROVED:** Recreation logic with better bot message detection
- **IMPROVED:** Safety checks for `bot.user` and `application_id`

---

### ✅ **v2.1.0 (2025-11-26) - Auto-Action System & Status Watchdog**

🤖 **Auto-Action System (AAS) - Intelligent Container Automation:**
- **NEW:** 🎮 **Game Server Auto-Updates** - Your Minecraft/Valheim/Palworld server restarts automatically when update bots announce new versions. No more manual restarts!
- **NEW:** 🔗 **Universal Webhook Control** - Trigger container actions from ANY external event: CI/CD pipelines, monitoring alerts, GitHub Actions, home automation, or custom scripts
- **NEW:** 📝 **Flexible Triggers** - Match Discord messages by keywords (with fuzzy search) or regex patterns
- **NEW:** 🛡️ **Built-in Safety** - Cooldowns prevent spam, protected containers can't be accidentally stopped, atomic locking ensures clean operations
- **🔒 Zero Attack Surface** - DDC only makes outbound connections to Discord - no open ports, no exposed APIs! External triggers flow through Discord's secure infrastructure. Full automation power without exposing Docker or your network.

🔔 **Status Watchdog (Dead Man's Switch):**
- **NEW:** Get alerts when DDC goes offline via external monitoring
- **NEW:** Simple setup - just paste a URL from Healthchecks.io or Uptime Kuma
- **SECURE:** Only outbound HTTPS pings - no tokens shared, no incoming connections
- Compatible with 20+ monitoring services

🏗️ **Architecture Improvements:**
- **IMPROVED:** Single-process architecture (removed supervisord & gunicorn)
- **IMPROVED:** 65% RAM reduction - from ~200MB to 60-70MB typical usage
- **IMPROVED:** Unified logging system with consistent formatting
- **IMPROVED:** Service-first architecture with single point of truth
- Cleaner codebase with reduced complexity

---

### ✅ **v2.0.0 (2025-11-18) - MAJOR UPDATE - Complete Rewrite**

🎮 **EVERYTHING via Discord - Complete Control:**
- **NEW:** Live Logs Viewer - Monitor container output in real-time directly in Discord
- **NEW:** Task System - Create, view, delete tasks (Once, Daily, Weekly, Monthly, Yearly) entirely in Discord
- **NEW:** Container Info System - Attach custom info and password-protected info to containers
- **NEW:** Public IP Display - Automatic WAN IP detection with custom port support
- Full container management without leaving Discord (start, stop, restart, bulk operations)

🌍 **Multi-Language Support:**
- **NEW:** Full Discord UI translation in German, French, and English
- Complete language coverage for all buttons, messages, and interactions
- Dynamic language switching via Web UI settings
- 100% translation coverage across entire bot interface

🤖 **Mech Evolution System:**
- **NEW:** 11-stage Mech Evolution with animated WebP graphics
- Continuous power decay system (minutengenau) for fair donation tracking
- Premium key system for power users
- Visual feedback with stage-specific animations and particle effects

⚡ **Performance Improvements:**
- **IMPROVED:** 16x faster Docker status cache (500ms → 31ms)
- 7x faster container processing through async optimization
- Smart queue system with fair request processing
- Operation-specific timeout optimization

🎨 **Modern UI/UX Overhaul:**
- **IMPROVED:** Beautiful Discord embeds with consistent styling
- Advanced spam protection with configurable cooldowns
- Enhanced container information system
- Real-time monitoring and status updates

🔒 **Security & Optimization:**
- **IMPROVED:** Alpine Linux 3.23.3 base (94% fewer vulnerabilities)
- Ultra-compact image (<200MB RAM usage)
- Production-ready security hardening
- Enhanced token encryption and validation

🐛 **Critical Fixes:**
- **FIXED:** Port mapping consistency (9374) for Unraid deployment
- Interaction timeout issues with defer() pattern
- Container control reliability improvements
- Web UI configuration persistence

**🚀 Ready for Unraid Community Applications! Now with Auto-Action System for automatic updates and Status Watchdog for offline alerts!**

## Platform Selection

**DockerDiscordControl is now available with platform-optimized versions!**

| Platform | Repository | Description | Best For |
|----------|------------|-------------|----------|
| **Windows** | **[DockerDiscordControl-Windows](https://github.com/DockerDiscordControl/DockerDiscordControl-Windows)** | Windows Docker Desktop optimized | Windows 10/11 + Docker Desktop |
| **Linux** | **[DockerDiscordControl-Linux](https://github.com/DockerDiscordControl/DockerDiscordControl-Linux)** | Native Linux optimization | Ubuntu, Debian, CentOS, RHEL |
| **macOS** | **[DockerDiscordControl-Mac](https://github.com/DockerDiscordControl/DockerDiscordControl-Mac)** | Apple Silicon & Intel Mac optimized | macOS + Docker Desktop |
| **Universal** | **[DockerDiscordControl](https://github.com/DockerDiscordControl/DockerDiscordControl)** *(this repo)* | Multi-platform, Unraid focus | Unraid, NAS, servers |

### Quick Platform Selection:

- **Windows Users** → [**Windows Version**](https://github.com/DockerDiscordControl/DockerDiscordControl-Windows) *(PowerShell scripts, WSL2 optimized)*
- **Linux Users** → [**Linux Version**](https://github.com/DockerDiscordControl/DockerDiscordControl-Linux) *(Native systemd, package managers)*  
- **macOS Users** → [**Mac Version**](https://github.com/DockerDiscordControl/DockerDiscordControl-Mac) *(Apple Silicon + Intel, Homebrew)*
- **Unraid/NAS Users** → **Use this repository** *(Universal, Community Apps support)*

---

## v1.1.2-alpine: Ultra-Optimized & Secure

**Release v1.1.2-alpine brings massive performance improvements with an ultra-optimized Alpine Linux image.**
- **78% Size Reduction**: From 924MB to ~200MB - ultra-optimized Alpine Linux 3.23.3
- **Latest Security Patches**: Upgraded to Flask 3.1.1 and Werkzeug 3.1.3 to resolve all critical and high-severity CVEs
- **Enhanced Performance**: Faster startup times and reduced memory footprint
- **Docker Socket Fixes**: Resolved permissions and volume mount issues
- **Complete Functionality**: All features preserved while dramatically reducing resource usage

## Features - EVERYTHING via Discord! 🚀

### 🤖 Auto-Action System (AAS) - Intelligent Container Automation
- **🎮 Game Server Auto-Updates**: Palworld, Valheim, Minecraft, or any game server - automatically restart when Discord update bots announce new versions. Set it and forget it!
- **🔗 Universal Webhook Control**: Control containers from ANY external system - CI/CD pipelines (Jenkins, GitLab), monitoring alerts (Grafana, Prometheus), GitHub Actions, Home Assistant, IFTTT, or your own scripts. One webhook URL, endless possibilities!
- **🔒 Zero Attack Surface**: DDC only makes outbound connections to Discord - no open ports, no exposed APIs, no attack surface! All automation flows through Discord's secure infrastructure. Your Docker socket and network stay completely protected.
- **📝 Flexible Triggers**: Match Discord messages by keywords ("update available", "new version") with optional fuzzy matching, or use regex for complex patterns
- **🛡️ Built-in Safety**: Cooldowns prevent trigger spam, mark containers as protected to prevent accidental stops, atomic locking ensures clean operations
- **🎯 Multi-Container Actions**: Restart your entire game server stack (game + database + proxy) with a single trigger

### 🔔 Status Watchdog
- **Dead Man's Switch**: Get alerts when DDC goes offline
- **External Monitoring**: Works with Healthchecks.io, Uptime Kuma, Cronitor, and more
- **Secure Design**: Only outbound HTTPS pings - no tokens shared, no incoming connections
- **Simple Setup**: Just paste a monitoring URL from your preferred service
- **Flexible Intervals**: Configure ping frequency from 1-60 minutes

### 🎮 Discord Container Control
- **Start, Stop, Restart** individual containers or **ALL containers at once**
- **Live Logs Viewer** - Monitor container output in real-time directly in Discord
- **Attach Custom Info** to containers (e.g., current WAN IP address, connection details)
- **Password-Protected Info** for secure data sharing within your Discord community
- **Container Status** monitoring with real-time updates

### 📅 Discord Task Scheduler
- **Create, view, and delete** automated tasks directly in Discord channels
- **Flexible Scheduling**: Once, Daily, Weekly, Monthly, Yearly
- **Full Task Management** - Complete control without leaving Discord
- **Timezone Configuration** for accurate scheduling across regions

### 🔒 Flexible Permissions System
- **Status Channels**: All members see container status and public info
- **Status Channels**: Admin users get admin panel access for full control
- **Control Channels**: Everyone gets full admin access to all features
- **Granular Container Permissions**: Fine-grained control per container (Status, Start, Stop, Restart, Active visibility)
- **Hide Containers** from Discord or configure custom visibility per container
- **Password-Protected Info**: Viewable by anyone who knows the password
- **Spam Protection**: All Discord commands and button clicks protected by configurable cooldowns

### 🌐 Web Interface
- **Secure Configuration Panel** with real-time monitoring
- **Container Management**: Configure permissions, custom info, and visibility
- **Task Management**: Create and manage scheduled tasks
- **Admin User Management**: Define who gets admin panel access in status channels
- **Security Audit**: Built-in security scoring and recommendations

### 🎨 Customization & Localization
- **Multi-Language Support**: Full Discord UI in English, German, and French
- **Customizable Container Order**: Organize containers in your preferred display order
- **Mech Evolution System**: 11-stage evolution with animated graphics and premium keys
- **Custom Branding**: Configure container display names and information

### ⚡ Performance & Optimization
- **16x Faster Docker Cache**: Optimized from 500ms to 31ms response time
- **7x Faster Processing**: Through async optimization and smart queue system
- **Ultra-Low Memory**: Only 60-70MB RAM usage (65% reduction in v2.1.0)
- **Alpine Linux 3.23.3**: 94% fewer vulnerabilities, minimal footprint
- **Production Ready**: Supports 50 containers across 15 Discord channels
- **Intelligent Caching**: Background refresh for real-time data

**New in v1.1.2-alpine:** The default build is now an ultra-optimized ~200MB Alpine Linux image with 78% size reduction while maintaining full functionality and improving security.

**Latest Updates:** Upgraded to Flask 3.1.1 and Werkzeug 3.1.3, resolved all security vulnerabilities, and achieved massive optimization with Alpine Linux 3.23.3 base image.

## 🧪 Testing & Quality Assurance

DockerDiscordControl maintains **86% test coverage** (3480 tests) with comprehensive automated testing:

### Test Suites
- **Unit Tests**: Service-level testing for core business logic
- **Integration Tests**: End-to-end workflow validation
- **Performance Tests**: Benchmarking and profiling with Locust
- **Security Tests**: Static Analysis Security Testing (SAST) with bandit & semgrep

### Continuous Integration
All code changes are automatically validated through GitHub Actions:
- ✅ **Automated Testing** - pytest with 86% coverage
- ✅ **Code Quality** - pylint, flake8, mypy type checking
- ✅ **Security Scanning** - bandit, semgrep, safety dependency checks
- ✅ **Performance Benchmarks** - Automated performance regression testing

### Running Tests Locally

```bash
# Install test dependencies
pip install -r requirements-test.txt

# Run all tests
pytest

# Run with coverage report
pytest --cov=services --cov=app --cov=utils --cov-report=html

# Open coverage report
open htmlcov/index.html
```

### Development Branch

For active development with additional debug tools and utilities, check out the `v2.0` branch:

```bash
git checkout v2.0
```

The `v2.0` development branch includes:
- Additional debug scripts (`debug_*.py`)
- Fix utilities (`fix_*.sh`)
- Ad-hoc testing tools
- Development documentation

The `main` branch contains production-ready code with comprehensive test infrastructure.

## ⚠️ Deployment Security

**Important:** DDC is designed for **private network deployment** (LAN/VPN).

- ✅ **Safe:** Deploy on private networks (192.168.x.x, 10.x.x.x) behind firewall
- ✅ **Safe:** Access via VPN (Tailscale, WireGuard, OpenVPN)
- ⚠️ **Not recommended:** Direct internet exposure without additional security

**If you need internet access:**
- Use a reverse proxy (nginx, Traefik, Caddy) with HTTPS
- Enable additional authentication (OAuth, SSO)
- Consider VPN access instead of public exposure

DDC includes HTTP Basic Auth and rate limiting, but these are designed for trusted network environments.

## 🚀 Quick Start

### **Platform-Specific Installation (Recommended)**

**Choose your platform for optimized experience:**

#### **Windows Users**
Visit: **[DockerDiscordControl-Windows](https://github.com/DockerDiscordControl/DockerDiscordControl-Windows)**
```powershell
# Clone Windows-optimized version
git clone https://github.com/DockerDiscordControl/DockerDiscordControl-Windows.git
cd DockerDiscordControl-Windows
# Follow Windows-specific setup guide
```

#### **Linux Users** 
Visit: **[DockerDiscordControl-Linux](https://github.com/DockerDiscordControl/DockerDiscordControl-Linux)**
```bash
# Clone Linux-optimized version
git clone https://github.com/DockerDiscordControl/DockerDiscordControl-Linux.git
cd DockerDiscordControl-Linux
# Follow Linux-specific setup guide
```

#### **macOS Users**
Visit: **[DockerDiscordControl-Mac](https://github.com/DockerDiscordControl/DockerDiscordControl-Mac)**
```bash
# Clone Mac-optimized version  
git clone https://github.com/DockerDiscordControl/DockerDiscordControl-Mac.git
cd DockerDiscordControl-Mac
# Follow macOS-specific setup guide
```

---

### **Universal Installation (Unraid & Servers)**

**For Unraid, NAS systems, and server deployments:**

#### Prerequisites

1. **Create Discord Bot**: [Bot Setup Guide](../../wiki/Discord‐Bot‐Setup)
2. **Docker**: [Install Docker](https://docs.docker.com/engine/install/) + [Docker Compose](https://docs.docker.com/compose/install/)

#### Installation Methods

**Method 1: Docker Compose (Recommended)**

```bash
# Clone repository
git clone https://github.com/DockerDiscordControl/DockerDiscordControl.git
cd DockerDiscordControl

# Create directories
mkdir config logs

# Create .env file with secure secret key
echo "FLASK_SECRET_KEY=$(openssl rand -hex 32)" > .env

# Start container
docker compose up --build -d
```

**Method 2: Docker Hub (Direct)**

```bash
# Pull and run latest Alpine-optimized image
docker run -d --name ddc \
  -p 9374:9374 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ./config:/app/config \
  -v ./logs:/app/logs \
  -e FLASK_SECRET_KEY="$(openssl rand -hex 32)" \
  --restart unless-stopped \
  dockerdiscordcontrol/dockerdiscordcontrol:latest
```

**Method 3: Unraid (Recommended for Unraid users)**
- Install via **Community Applications**
- Search for "DockerDiscordControl"
- **One-click install** with pre-configured paths
- [📖 Detailed Unraid Setup](docs/UNRAID.md)

#### First-Time Setup

**🚀 Easy Web Setup (Recommended)**

1. **Access Web UI**: `http://<your-server-ip>:9374`
2. **Setup Options**:
   - **Method 1**: Visit `/setup` for guided web setup
   - **Method 2**: Use temporary credentials: `admin` / `setup` 
   - **Method 3**: Set `DDC_ADMIN_PASSWORD=your_password` before starting

3. **Complete Setup**: Configure bot token, Guild ID, container permissions
4. **Restart**: `docker compose restart` after initial configuration

**Security Note**: Default password is 'setup' for initial access. MUST be changed immediately after first login for security!

**Upgrade from v1.1.3D**: Automatic migration! Your existing `config.json` will be automatically split into modular files and backed up. No manual action required.

## Environment Variables

### Security & Authentication

**🔐 Password Setup Options:**

```bash
# Option 1: Set admin password before first start (Recommended)
DDC_ADMIN_PASSWORD=your_secure_password_here

# Option 2: Use temporary credentials for web setup
# Visit http://your-server:9374 and login with: admin / setup
# Then complete setup through the web interface

# Flask security (auto-generated if not provided)
FLASK_SECRET_KEY=your-64-character-random-secret-key
```

**Important**: The default password is 'setup' for security setup. You MUST change this immediately after first login. For production deployments, set DDC_ADMIN_PASSWORD before first start.

### Performance Optimization Variables (New in 2025)

DDC now includes advanced performance optimization settings that can be configured via environment variables:

#### Memory Optimization
```bash
# Docker Cache Settings - Optimized for 1-minute Web UI updates
DDC_MAX_CACHED_CONTAINERS=100          # Maximum containers in cache (default: 100)
DDC_DOCKER_CACHE_DURATION=45           # Cache duration in seconds (default: 45, supports 1-min updates)
DDC_DOCKER_MAX_CACHE_AGE=90            # Maximum cache age before forced refresh (default: 90)
DDC_CACHE_CLEANUP_INTERVAL=300         # Memory cleanup interval in seconds (default: 300)

# Background Refresh Settings - CRITICAL for 1-minute Web UI updates
DDC_ENABLE_BACKGROUND_REFRESH=true     # Enable background Docker cache refresh (default: true)
DDC_BACKGROUND_REFRESH_INTERVAL=30     # Background refresh interval (default: 30, required for 1-min updates)
```

#### CPU Optimization
```bash
# Scheduler Service Settings
DDC_SCHEDULER_CHECK_INTERVAL=120       # Scheduler check interval in seconds (default: 120)
DDC_MAX_CONCURRENT_TASKS=3             # Maximum concurrent tasks (default: 3)
DDC_TASK_BATCH_SIZE=5                  # Task batch processing size (default: 5)
```

#### Permission Settings (NAS/Unraid)
```bash
# User/Group mapping for NAS systems
PUID=99                                # User ID (Unraid: 99, Synology: 1026)
PGID=100                               # Group ID (Unraid: 100, Synology: 100)
DDC_ADMIN_PASSWORD=your_password       # Required: Admin password for Web UI
```

#### Cache Control
```bash
# Configuration Cache
DDC_CONFIG_CACHE_AGE_MINUTES=15        # Config cache age in minutes (default: 15)

# Docker Query Settings
DDC_DOCKER_QUERY_COOLDOWN=1.0          # Minimum time between Docker API requests (default: 1.0)
```

### Performance Monitoring

Access real-time performance statistics via the Web UI at `/performance_stats` (requires authentication). This endpoint provides:

- **Memory Usage**: RAM consumption of all components
- **Cache Statistics**: Hit/miss ratios and cleanup times
- **System Resources**: CPU, memory, and thread monitoring
- **Scheduler Stats**: Task execution and batching metrics

### Recommended Settings by Deployment Size

#### Small Deployment (1-2 CPU cores, <2GB RAM)
```bash
DDC_MAX_CACHED_CONTAINERS=50
DDC_SCHEDULER_CHECK_INTERVAL=180
DDC_MAX_CONCURRENT_TASKS=2
```

#### Medium Deployment (2-4 CPU cores, 2-4GB RAM)
```bash
DDC_MAX_CACHED_CONTAINERS=100
DDC_SCHEDULER_CHECK_INTERVAL=120
DDC_MAX_CONCURRENT_TASKS=3
```

#### Large Deployment (4+ CPU cores, 4GB+ RAM)
```bash
DDC_MAX_CACHED_CONTAINERS=200
DDC_SCHEDULER_CHECK_INTERVAL=90
DDC_MAX_CONCURRENT_TASKS=5
```

### Ultra-Optimized Alpine Image

The default build for this repository is now the stable, optimized Alpine image. To build it locally, simply use the standard rebuild script:

```bash
# This script now uses the optimized Dockerfile by default
./scripts/rebuild.sh
```

**Optimization Features:**
- **~50% smaller image size** compared to older Debian-based builds.
- **Stable and reliable** single-stage Docker build process.
- **Minimal runtime dependencies** - only essential packages included.
- **Production-only requirements** - testing dependencies excluded.
- **Latest security patches** for all dependencies.

**Important Cache Timing**: The Docker cache is updated every 30 seconds with a 45-second cache duration to ensure fresh data for users who set 1-minute update intervals in the Web UI. This timing is critical for maintaining data freshness at the minimum supported interval.

**Note**: All Web UI configuration options remain fully functional regardless of these performance optimizations. The interval frequency settings and all other configuration capabilities are preserved and unaffected.

## 🐳 Docker Images

**Ultra-optimized Alpine Linux image:**
- **Size:** 176MB with multi-stage build optimization
- **Base:** Alpine Linux 3.23.3 (latest secure version)  
- **Architecture:** Service-oriented modular design (v2.0)
- **Security:** Latest dependencies with all CVEs fixed
- **Performance:** Optimized for minimal resource usage and fast startup

```bash
docker pull dockerdiscordcontrol/dockerdiscordcontrol:latest
```

## System Requirements

### **Minimum Requirements**
- **CPU**: 1 core (1.5 cores recommended)
- **RAM**: 60-70MB typical usage (65% reduction in v2.1.0)
- **Storage**: 100MB for application + config/logs space
- **Docker**: Docker Engine 20.10+ and Docker Compose 2.0+

### **Production Limits**
- **Maximum Containers**: 50 Docker containers
- **Maximum Channels**: 15 Discord channels  
- **Concurrent Operations**: 10 pending Docker actions
- **Cache Size**: 50 status entries with intelligent cleanup

### **Platform Support**

#### **🔧 This Universal Repository**
- **Unraid**: Native Community Applications support ⭐
- **Linux Servers**: x86_64, ARM64 (Raspberry Pi)
- **Docker**: Swarm, Compose, Standalone
- **NAS**: Synology, QNAP, TrueNAS

#### **🎯 Platform-Optimized Repositories**
- **🪟 [Windows](https://github.com/DockerDiscordControl/DockerDiscordControl-Windows)**: Docker Desktop, WSL2, PowerShell integration
- **🐧 [Linux](https://github.com/DockerDiscordControl/DockerDiscordControl-Linux)**: Native systemd, package managers, distributions
- **🍎 [macOS](https://github.com/DockerDiscordControl/DockerDiscordControl-Mac)**: Apple Silicon, Intel, Homebrew, Docker Desktop

## Documentation

| Topic | Description |
|-------|-------------|
| [Installation Guide](../../wiki/Installation‐Guide) | Detailed setup for all platforms |
| [Configuration](../../wiki/Configuration) | Web UI, permissions, channels |
| [Auto-Action System](../../wiki/Auto‐Action‐System) | Automatic triggers, keywords, regex, webhooks |
| [Status Watchdog](../../wiki/Status‐Watchdog) | Dead Man's Switch monitoring setup |
| [Task System](../../wiki/Task‐System) | Automated scheduling system |
| [Performance](../../wiki/Performance‐and‐Architecture) | V3.0 optimizations & monitoring |
| [Alpine Migration](../../wiki/Alpine‐Linux‐Migration) | Benefits, security, optimization |
| [Memory Optimization](../../wiki/Memory‐Optimization) | Resource management, limits |
| [Unraid Setup](docs/UNRAID.md) | Community Applications guide |
| [Troubleshooting](../../wiki/Troubleshooting) | Common issues & solutions |
| [Development](../../wiki/Development) | Contributing & development setup |
| [Security](../../wiki/Security) | Best practices & considerations |

## ⚠️ Security Notice

**Docker Socket Access Required**: This application requires access to `/var/run/docker.sock` to control containers. Only run in trusted environments and ensure proper host security.

**First-Time Setup Required**: DDC v2.0+ uses temporary default password 'setup' for initial access. Use one of these secure setup methods:
- **Web Setup**: Visit `/setup` and create your password  
- **Temporary Access**: Login with `admin` / `setup`, then set real password
- **Environment Variable**: Set `DDC_ADMIN_PASSWORD` before starting container

**Password Security**: All passwords are hashed with PBKDF2-SHA256 (600,000 iterations) for maximum security.

## Quick Help

**First-Time Setup Issues:**
- **Can't Login**: Visit `/setup` or use `admin` / `setup` credentials
- **"Authentication Required"**: Use default credentials `admin` / `setup` or configure DDC_ADMIN_PASSWORD
- **Password Reset**: Run `docker exec -it ddc python3 scripts/reset_password.py`

**Common Issues:**
- **Permission Errors**: Run `docker exec ddc /app/scripts/fix_permissions.sh`
- **Configuration Not Saving**: Check file permissions in logs
- **Bot Not Responding**: Verify token and Guild ID in Web UI

**Need Help?** Check our [Troubleshooting Guide](../../wiki/Troubleshooting) or create an issue.

## Contributing

We welcome contributions! See our [Development Guide](../../wiki/Development) for setup instructions and coding standards.

**Contributing to Platform-Specific Versions:**
- **Windows**: [Contribute to Windows version](https://github.com/DockerDiscordControl/DockerDiscordControl-Windows)
- **Linux**: [Contribute to Linux version](https://github.com/DockerDiscordControl/DockerDiscordControl-Linux)
- **macOS**: [Contribute to Mac version](https://github.com/DockerDiscordControl/DockerDiscordControl-Mac)

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

### Third-party libraries

Live game-server player counts are powered by **[opengsq](https://github.com/opengsq/opengsq-python)** (MIT License) — the open-source game-server query library that also powers DiscordGSM. DDC uses it as a dependency (via `requirements.txt`); it is not modified or bundled.

---

**Like DDC? Star the repository!** | **Found a bug?** [Report it](../../issues) | **Feature idea?** [Suggest it](../../discussions)

**Don't forget to star the platform-specific repos too!** 
- **[Windows](https://github.com/DockerDiscordControl/DockerDiscordControl-Windows)**
- **[Linux](https://github.com/DockerDiscordControl/DockerDiscordControl-Linux)**  
- **[macOS](https://github.com/DockerDiscordControl/DockerDiscordControl-Mac)**

## Support DDC Development

Help keep DockerDiscordControl growing and improving across all platforms:

- **[Buy Me A Coffee](https://buymeacoffee.com/dockerdiscordcontrol)** - Quick one-time support
- **[PayPal Donation](https://www.paypal.com/donate/?hosted_button_id=XKVC6SFXU2GW4)** - Direct contribution

Your support helps maintain DDC across **Windows, Linux, macOS, and Universal** versions, develop new features, and keep it zero-vulnerability secure!

## Credits & Contributors

**DockerDiscordControl** is developed and maintained by:
- **Lead Developer**: MAX
- **Contributors**: Community contributions welcome via [Pull Requests](../../pulls)
- **Special Thanks**: All users who report bugs, suggest features, and support the project

Want to contribute? Check out our [Contributing Guidelines](docs/CONTRIBUTING.md)!

**Built for every platform - optimized for your environment!**

DockerDiscordControl

DockerDiscordControl Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

DockerDiscordControl

DockerDiscordControl Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README