🐳 Docker Orkes

A lightweight, agentless multi-node Docker deployment and host observability control plane based on declarative Docker Compose stacks.

Features • Architecture • Quick Start • Documentation • Tech Stack • Bahasa Indonesia 🇮🇩

---

Overview

Docker Orkes solves the operational gap between single-server docker compose and heavy cluster orchestrators like Kubernetes or Docker Swarm. It allows DevOps engineers and sysadmins to manage dozens of independent VPS or bare-metal servers through a single unified Control Plane without installing any agents, runners, or background daemons on the target hosts.

Everything is performed over secure, agentless SSH:

• Push declarative Docker Compose templates.
• Inject node-specific environment variables (.env).
• Monitor remote disk capacity and container runtimes in real time.
• Edit remote stack files live with an integrated SFTP code editor.
• Automatically detect configuration drift between desired state and actual remote state.
• Backup all stacks and deployment manifests to an external Git Mirror.

Design Philosophy: Pragmatic, Lean, and Self-Contained

• Agentless over Daemons: No agents or cluster daemons (Swarm/Kubernetes) consuming RAM or requiring maintenance on target nodes. Plain SSH and Docker are all you need.
• Declarative over Imperative: Manage applications as reproducible Compose templates and deployments with automatic drift detection, rather than ad-hoc container clicking.
• Agentless Vulnerability Scanning without Runtime Bloat: Docker Orkes audits container image security by executing ephemeral Trivy scanner containers directly on managed nodes via the SSH Executor, persisting CVE metrics in SQLite without embedding multi-gigabyte vulnerability databases into the Control Plane binary.
• 100% Self-Contained: Single static Go binary with zero external CDN dependencies, embedded SQLite, and embedded web terminal.

---

Key Features

• 🚀 Agentless SSH Architecture: Zero software footprint on target nodes. If the target server can run Docker and accept SSH connections, it can be managed by Docker Orkes.
• 📦 Declarative Stack Templates: Define reusable docker-compose.yml templates and deploy them across any target node with customized environment variables.
• 🎨 VS Code-Style Stack Editor & Validation Guardrails: Edit Docker Compose manifests and environment variables with embedded VS Code Dark styling, line numbers, 2-space automatic indentation, matching brackets, fullscreen workspace expansion (⛶), and instant pre-save syntax validation preventing invalid YAML or compose files without services: from being saved.
• 🔍 Real-Time Configuration Drift Detection: Verify SHA-256 checksums and review line-by-line diffs between the Control Plane's Desired State and the Actual State on remote nodes. Choose to either Reconcile (overwrite remote) or Adopt (pull remote changes into Git).
• 🛡️ Agentless Image Vulnerability Scanning & Cooldown Protocol: Audit Node container images for CVEs using transient Trivy containers with dedicated host caching (orkes-trivy-cache), 24-hour scan cooldown guards to prevent rate-limiting and host exhaustion, real-time background progress tracking, and interactive vulnerability report modals detailing package versions and CVE identifiers.
• 💻 100% Offline Interactive Web Terminal: Launch low-latency browser PTY terminal sessions over WebSocket directly into node host shells or running container environments (docker exec) with bundled offline xterm.js assets.
• 📜 Deployment Revisions & 1-Click Rollback: Maintain forward-only, immutable snapshot histories of compose configurations and environment variables with bounded retention for instant rollbacks.
• 📂 Remote Stack Filesystem & Runtime Assets: Full remote directory browser, file creation, drag-and-drop & recursive folder upload (webkitdirectory), remote archive extraction (.tar.gz, .zip), secret masking, and live code editing with instant redeployment.
• 🔔 Proactive Liveness Poller & Alerting: Automatic background auditing of host reachability, container health, and drift with edge-triggered webhook dispatches to Telegram, Discord, or generic endpoints.
• 📊 Host Observability & Container Logs: Real-time disk usage telemetry (df -h), Docker engine vitals, container port mappings, and live container logs viewer.
• 🔄 Automated Git Mirror Backup: Maintain an external Git repository (GitHub, GitLab, Gitea) as a versioned audit log of all stack templates, deployment variables, and inventory.
• ⚡ Auto-Inject SSH Key: Bootstrap new nodes automatically using temporary SSH passwords—the password is used once to append the Control Plane's public key to ~/.ssh/authorized_keys and is never saved.
• 📡 In-App Activity Console & Live Telemetry Stream: Real-time zero-polling diagnostic feed served via Server-Sent Events (SSE) with a 6-column running drawer (TIME | LEVEL | MODULE | TARGET/NODE | MESSAGE | DETAILS), smart auto-scroll, pause/resume, level filters, unread error counters, global hotkey (Ctrl+```), and client-side .logand.json` export.
• 🌐 Bilingual Interface: Seamlessly switch between English and Bahasa Indonesia with instant client-side localization.
• 📋 Shared Operator Runbook: Built-in operational checklist and infrastructure notes synchronized directly to your Git repository as RUNBOOK.md.

---

Architecture

                 ┌─────────────────────────────────────────┐
                 │       Docker Orkes Control Plane        │
                 │  (Go Single Binary + SQLite + embed.FS) │
                 └───────────────────┬─────────────────────┘
                                     │
         ┌───────────────────────────┼───────────────────────────┐
         │ SSH (Agentless)           │ SSH (Agentless)           │ Git SSH/HTTPS
         ▼                           ▼                           ▼
┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
│     Node 1      │         │     Node 2      │         │   Git Mirror    │
│  (Docker Host)  │         │  (Docker Host)  │         │(GitHub / GitLab)│
│                 │         │                 │         │                 │
│ ~/.docker-orkes │         │ ~/.docker-orkes │         │ - Stacks        │
│  /stacks/...    │         │  /stacks/...    │         │ - Deployments   │
└─────────────────┘         └─────────────────┘         │ - inventory.json│
                                                        │ - RUNBOOK.md    │
                                                        └─────────────────┘

---

Quick Start

Prerequisites

• Control Plane host: Linux or macOS with Go 1.22+ (or pre-compiled binary).
• Target Nodes: Any Linux server with Docker and SSH server enabled (systemctl status docker).

1. Build the Binary

git clone https://github.com/herliansyah/docker-orkes.git
cd docker-orkes
go build -o bin/docker-orkes ./cmd/docker-orkes

2. Launch Control Plane

./bin/docker-orkes -addr :8080 -pass your-secure-password

Open your browser and navigate to http://localhost:8080. Log in with your password.

Configuration Flags & Environment Variables

Flag	Environment Variable	Default	Description
-addr	ADDR	:8080	Web server listening address and port
-pass	MASTER_PASSWORD	admin	Master login password for the control plane
-db	DB_PATH	docker-orkes.db	SQLite database file path
-log-file	LOG_FILE	docker-orkes.log	Persistent rotating server log file path (empty to disable)
-log-level	LOG_LEVEL	info	Diagnostic logging level (debug, info, warn, error)

---

⚠️ Storage Architecture & Data Persistence Best Practices

Caution

NEVER STORE PERSISTENT APPLICATION DATA OR DATABASES INSIDE ~/.docker-orkes/

The Stack Directory (~/.docker-orkes/stacks/<stack-name>/) is reserved strictly for declarative configuration files (docker-compose.yml, .env) and lightweight auxiliary assets (Nginx configs, SSL certificates).

When an operator performs a Deployment Deletion with Data Purge, Docker Orkes executes docker compose down -v followed by an automated rm -rf on the Stack Directory. If persistent databases (e.g. ./data:/var/lib/mysql) are placed inside this directory, THEY WILL BE PERMANENTLY DESTROYED.

Built-in Guardrail: To protect against accidental destruction of misplaced databases, Docker Orkes audits the Stack Directory size before running rm -rf. If the directory exceeds 50 MB, the automated purge is blocked immediately by the Control Plane.

Proper Patterns for Dedicated Partitions & Persistent Data (e.g. /mydocker)

If your Node has a dedicated disk partition (e.g. /mydocker or /data) intended for Docker data:

1. Persistent Databases / App Storage: Always mount volumes using absolute host paths outside ~/.docker-orkes/ or Docker Named Volumes:

   services:
     db:
       image: mysql:8.0
       volumes:
         # ✅ CORRECT: Absolute host path on your dedicated partition
         - /mydocker/mysql-data:/var/lib/mysql
         # OR
         # ✅ CORRECT: Docker Named Volume (stored under Docker daemon's data-root)
         - mysql_data:/var/lib/mysql

2. Relocating Entire .docker-orkes to a Dedicated Partition: Do not modify application code. Use a native OS symbolic link on the Node:

   mkdir -p /mydocker/docker-orkes
   ln -s /mydocker/docker-orkes ~/.docker-orkes

   This offloads stack files transparently to your partition while maintaining full compatibility and sandboxing.

---

Documentation

Comprehensive guides and technical documentation are available:

• 📖 Getting Started Guide (English) | Panduan Memulai (Bahasa Indonesia)
• 🛠️ Feature Deep Dive & Architecture (English) | Rincian Fitur & Arsitektur (Bahasa Indonesia)
• 📦 Internal Hybrid Image Registry Setup (English) | Panduan Setup Registry Internal (Bahasa Indonesia)
• 🛡️ Disaster Recovery & Standby Setup (English) | Disaster Recovery & Standby Setup (Bahasa Indonesia)
• 📐 Architecture Decision Records (ADRs)
  • ADR 0001: Agentless SSH Architecture
  • ADR 0002: Control Plane Tech Stack
  • ADR 0003: Stack Template and Deployment Model
  • ADR 0004: Lightweight Liveness Poller and Edge-Triggered Alerting
  • ADR 0005: Forward-Only Deployment Revisions with Bounded Retention
  • ADR 0006: Active-Passive Control Plane Replication
  • ADR 0007: Internal Hybrid Image Registry Architecture
  • ADR 0008: Remote Stack Filesystem and Runtime Assets Management
  • ADR 0009: Offline Web Terminal Architecture via WebSocket and PTY
  • ADR 0010: Node Images and On-Demand Retention
  • ADR 0011: Self-Contained Enterprise UI
  • ADR 0012: Node Volumes and Networks Observability
  • ADR 0013: Deployment Deletion Lifecycle and Adoption Safety
  • ADR 0014: Deployment Preflight Checks and Execution Feedback
  • ADR 0015: Agentless Transport Security and Filesystem Isolation
  • ADR 0016: Stack Directory Isolation and Data Purge Guardrails
  • ADR 0017: In-App Activity Console and Live Telemetry Stream

---

Tech Stack

• Backend: Go (Standard Library + net/http routing)
• Database: SQLite with Modernc pure-Go driver (modernc.org/sqlite)
• Transport: golang.org/x/crypto/ssh & github.com/pkg/sftp
• Frontend: HTML5 Templates embedded at compile time (embed.FS) styled with Tailwind CSS
• Version Control: Pure-Go Git implementation (github.com/go-git/go-git/v5)

---

Contributing

Contributions, feature requests, and bug reports are welcome! Feel free to check the issues page.

---

License

Distributed under the MIT License. See LICENSE for more information.

Crafted with care by Herliansyah.