System Overview

webtop-manage is a lightweight, self-hosted orchestration engine and web dashboard built specifically for LinuxServer.io Docker Webtop desktop environments.

It replaces fragile shell scripts and manual docker run flags with an intuitive browser experience, complete with real-time provisioning streams, live resource gauges, interactive web terminals, and strict security isolation.

┌─────────────────────────────────────────────────────────────────────────────┐
│ 1. Enterprise Core: Domain Entities (internal/core/domain/)                 │
│    • Pure models (Instance, Preset, DistroMatrix, Telemetry, Storage)       │
│    • Zero external dependencies or framework imports                        │
├─────────────────────────────────────────────────────────────────────────────┤
│ 2. Application Core: Use Cases & Ports (internal/core/usecase/, ports/)     │
│    • Business orchestrators (InstanceUC, TelemetryUC, TerminalUC, NetworkUC)│
│    • Port interfaces (InstanceRepository, NetworkGateway, TelemetryGateway) │
├─────────────────────────────────────────────────────────────────────────────┤
│ 3. Interface Adapters: Primary & Secondary (internal/adapters/)             │
│    • Primary / Driving: HTTP, SSE & WS Controllers (adapters/primary/http/) │
│    • Secondary / Driven: Docker SDK & System FS (adapters/secondary/)       │
├─────────────────────────────────────────────────────────────────────────────┤
│ 4. Composition Root & Delivery (cmd/webtop-manage/main.go)                  │
│    • Pure Dependency Injection, embedded web assets, graceful shutdown      │
└─────────────────────────────────────────────────────────────────────────────┘

⚡ Core Architectural Pillars

• 100% Stateless Backend (Zero Database Overhead): webtop-manage requires no SQLite, PostgreSQL, or Redis. All metadata, presets, egress policies, and volume tags are persisted directly in Docker Container Labels (webtop.managed=true, webtop.owner=<name>).
• Zero-Trust Localhost Binding: The management dashboard (8080) and desktop instances (3000+) default strictly to 127.0.0.1. Remote LAN and WAN connections receive Connection Refused out of the box.
• Dual-Track Provisioning Wizard:
  • Quick Launch Track: 1-click curated templates (Ubuntu XFCE/KDE, Debian KDE/XFCE) with image cache detection and pre-pull helpers.
  • Custom Blueprint Track: Fine-grained distro matrix, port allocation, CPU/RAM limits, GPU acceleration, and custom volume mounts.
• Real-Time Streaming Subsystems:
  • Server-Sent Events (SSE): Streams layer-by-layer image download progress, live CPU % and Memory metrics, and container logs.
  • In-Browser Web Terminal (WebSockets + xterm.js): Direct PTY interactive shell (/bin/bash or /bin/sh) with dynamic window resize synchronization.
• Single Native Binary with Embedded Assets: All frontend assets (HTML5, CSS, modular JS, xterm.js) are embedded directly into the Go binary via Go 1.16+ //go:embed.

📋 System Prerequisites

🧭 Next Steps

• 1-Minute Quickstart & Deployment
• Dual-Track Provisioning Wizard Guide
• Security & Sandboxing Architecture