feat: add a docker stats widget to dashboard

[raghavyuva]

Describe the bug
The dashboard currently does not provide any real-time visibility into container resource usage. Users cannot see CPU, memory, network, or disk utilization for the Docker containers

Steps to reproduce the behavior:

1. Go to the Nixopus dashboard
2. Observe that no resource-usage widget exists
3. There is no section showing CPU or memory usage of running containers

Expected behavior
A Docker Stats widget should appear on the dashboard and show:

• List of all running containers
• CPU usage (%)
• Memory usage (used / total)
• Network I/O
• Disk I/O (optional)
• Uptime
• Auto-refresh every few seconds or manual refresh

[linear]

NIX-175

[raghavyuva]

@coderabbitai search through codebase and provide a detailed action plan on how to solve this step by step, keep this widget optional in the dashboard, do not enable it by default, we need to make sure that the solution is distro agonostic, works well with multi server architecture as well, refer to #549 for multi server changes, follow the feature request issue template

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash

# First, let's understand the repository structure
echo "=== Repository Structure ==="
fd -t d -d 1

echo -e "\n=== Looking for dashboard-related files ==="
fd -t f dashboard

echo -e "\n=== Looking for widget-related files ==="
fd -t f widget

echo -e "\n=== Looking for Docker-related files ==="
fd -t f -e py -e js -e ts -e jsx -e tsx docker

echo -e "\n=== Looking for configuration files ==="
fd -t f -e yaml -e yml -e json -e toml config

echo -e "\n=== Checking main directories for Python/JS/TS files ==="
fd -t f -e py -e js -e ts -e jsx -e tsx -d 2

Length of output: 941

---

🏁 Script executed:

#!/bin/bash

# Get details about issue #549 for multi-server changes
echo "=== Issue #549 Details ==="
gh issue view 549 --json title,body,comments --jq '.title, .body, .comments[].body'

Length of output: 16405

---

🏁 Script executed:

#!/bin/bash

# Look for README to understand project structure
echo "=== README Contents ==="
cat README.md 2>/dev/null || echo "No README.md found at root"

# Check for package.json or requirements.txt to understand tech stack
echo -e "\n=== Package files ==="
cat package.json 2>/dev/null || echo "No package.json"
cat requirements.txt 2>/dev/null || echo "No requirements.txt"
cat pyproject.toml 2>/dev/null || echo "No pyproject.toml"

Length of output: 4766

---

🏁 Script executed:

#!/bin/bash

# Explore the dashboard structure and existing widgets
echo "=== Dashboard Components Structure ==="
fd -t f . view/app/dashboard/components

echo -e "\n=== Containers Widget Content ==="
cat view/app/dashboard/components/containers/containers-widget.tsx

echo -e "\n=== Widget Selector Content ==="
cat view/app/dashboard/components/widget-selector.tsx

echo -e "\n=== Dashboard Hook ==="
cat view/app/dashboard/hooks/use-dashboard.ts

Length of output: 6673

---

🏁 Script executed:

#!/bin/bash

# Look for Docker-related code in the API
echo "=== Docker-related files in API ==="
fd -t f . api/internal/features/deploy/docker

echo -e "\n=== Docker service init (relevant to SSH tunnel) ==="
head -100 api/internal/features/deploy/docker/init.go

echo -e "\n=== Looking for stats or monitoring related code ==="
rg -n "stats" api/internal/features/deploy/docker/ -A 2 -B 2

Length of output: 4504

---

🏁 Script executed:

#!/bin/bash

# Check for existing configuration patterns and optional features
echo "=== Looking for feature flags or optional configurations ==="
rg -n "optional|enabled|disabled|feature" view/app/dashboard/components/ -A 2 -B 2

echo -e "\n=== Config files structure ==="
cat helpers/config.prod.yaml

Length of output: 5340

---

🏁 Script executed:

#!/bin/bash

# Explore API endpoints for dashboard/monitoring
echo "=== API routes structure ==="
fd -t f route api/internal/

echo -e "\n=== Looking for realtime/monitoring endpoints ==="
cat api/internal/realtime/dashboard_monitor.go

Length of output: 3383

---

🏁 Script executed:

#!/bin/bash

# Look for server/multi-server architecture
echo "=== Looking for server-related models and types ==="
rg -n "type.*Server" api/internal/ --type go -A 5 | head -100

echo -e "\n=== Looking for SSH tunnel usage ==="
rg -n "SSHTunnel|ssh_tunnel" api/internal/ --type go -A 3 -B 3

Length of output: 6825

---

🏁 Script executed:

#!/bin/bash

# Look at dashboard monitoring operations and features
echo "=== Dashboard Monitor Implementation ==="
fd -t f . api/internal/features/dashboard

echo -e "\n=== Dashboard Monitor Main File ==="
cat api/internal/features/dashboard/dashboard_monitor.go 2>/dev/null || echo "File not found"

Length of output: 316

---

🏁 Script executed:

#!/bin/bash

# Look for Docker stats usage
echo "=== Looking for Docker stats API usage ==="
rg -n "ContainerStats|Stats" api/internal/ --type go -A 3 -B 3

echo -e "\n=== Looking for existing monitoring operations ==="
rg -n "DashboardOperation|Operation" api/internal/features/dashboard/ --type go -A 2 -B 2

Length of output: 21274

---

🏁 Script executed:

#!/bin/bash

# Check feature flags implementation
echo "=== Feature flags types ==="
cat view/types/feature-flags.ts 2>/dev/null || echo "Not found"

echo -e "\n=== Looking for feature flag usage patterns ==="
rg -n "FeatureMonitoring|isFeatureEnabled" view/ -A 2 -B 2 | head -80

Length of output: 6005

---

🏁 Script executed:

#!/bin/bash

# Look at the main dashboard page to understand current architecture
echo "=== Dashboard Page Implementation ==="
cat view/app/dashboard/page.tsx 2>/dev/null || echo "Not found"

Length of output: 9177

---

🏁 Script executed:

#!/bin/bash

# Check for existing Docker service methods
echo "=== Docker Service Interface and Stats Methods ==="
rg -n "func.*Container.*Stats" api/internal/features/deploy/docker/ --type go -A 10 -B 2

Length of output: 50

---

🏁 Script executed:

#!/bin/bash

# Look at server model and multi-server related code
echo "=== Server Model Details ==="
cat api/internal/types/domain.go | grep -A 30 "type Server"

echo -e "\n=== Looking for server endpoints ==="
fd -t f server api/internal/features/

Length of output: 1139

---

🏁 Script executed:

#!/bin/bash

# Check Docker SDK for stats support
echo "=== Looking at Docker Client usage and available methods ==="
cat api/internal/features/deploy/docker/init.go | head -150

echo -e "\n=== Looking for Docker SSH tunnel implementation ==="
fd -t f ssh_tunnel api/internal/features/deploy/docker/

Length of output: 5617

---

🏁 Script executed:

#!/bin/bash

# Check if there's any existing server management
echo "=== Looking for server management features ==="
fd -t d server api/internal/features/

echo -e "\n=== Check types for Docker stats ==="
cat api/internal/features/container/types/container_types.go

Length of output: 3661

---

🏁 Script executed:

#!/bin/bash

# Look at Redux types for monitoring
echo "=== Redux Monitor Types ==="
cat view/redux/types/monitor.ts 2>/dev/null || echo "Not found"

echo -e "\n=== Check useMonitor hook ==="
cat view/app/dashboard/hooks/use-monitor.ts 2>/dev/null || cat view/app/dashboard/hooks/use-monitor.tsx 2>/dev/null || echo "Not found"

Length of output: 5443

---

🏁 Script executed:

#!/bin/bash

# Check if there are existing optional widget patterns
echo "=== Looking for widget configuration or settings ==="
rg -n "hiddenWidgets|defaultHiddenWidgets|widget.*config" view/app/dashboard/ --type ts --type tsx -A 3 -B 3

Length of output: 80

---

🏁 Script executed:

#!/bin/bash

# Get more details about the Docker init and cluster
echo "=== Full Docker init.go ==="
cat api/internal/features/deploy/docker/init.go

Length of output: 16065

---

@raghavyuva, I've analyzed the codebase and reviewed issue #549. Here's a comprehensive step-by-step action plan for implementing an optional Docker stats widget that's distro-agnostic and multi-server compatible:

📋 Detailed Action Plan: Docker Stats Widget

Phase 1: Backend API Implementation

Step 1.1: Add Docker Stats Types (api/internal/features/dashboard/types.go)

// Add new dashboard operation
const (
    GetContainers  DashboardOperation = "get_containers"
    GetSystemStats DashboardOperation = "get_system_stats"
    GetDockerStats DashboardOperation = "get_docker_stats"  // NEW
)

// Update AllOperations (but don't add to default - make it opt-in)
var AllOperations = []DashboardOperation{
    GetContainers,
    GetSystemStats,
    // GetDockerStats deliberately excluded from default
}

// Add Docker stats structures
type DockerStatsData struct {
    ContainerID   string              `json:"container_id"`
    ContainerName string              `json:"container_name"`
    Stats         ContainerStatsInfo  `json:"stats"`
    Timestamp     time.Time           `json:"timestamp"`
}

type ContainerStatsInfo struct {
    CPUPercentage    float64 `json:"cpu_percentage"`
    MemoryUsage      uint64  `json:"memory_usage"`
    MemoryLimit      uint64  `json:"memory_limit"`
    MemoryPercentage float64 `json:"memory_percentage"`
    NetworkRx        uint64  `json:"network_rx"`
    NetworkTx        uint64  `json:"network_tx"`
    BlockRead        uint64  `json:"block_read"`
    BlockWrite       uint64  `json:"block_write"`
    PIDs             uint64  `json:"pids"`
}

Step 1.2: Implement Stats Collection (api/internal/features/deploy/docker/stats.go - new file)

package docker

import (
    "context"
    "encoding/json"
    "io"
    "github.com/docker/docker/api/types"
)

// GetContainerStats retrieves real-time stats for a specific container
// This works with both local and SSH-tunneled Docker connections
func (s *DockerService) GetContainerStats(containerID string) (*types.StatsJSON, error) {
    stats, err := s.Cli.ContainerStats(s.Ctx, containerID, false) // false = one-time stats
    if err != nil {
        return nil, err
    }
    defer stats.Body.Close()

    var statsJSON types.StatsJSON
    if err := json.NewDecoder(stats.Body).Decode(&statsJSON); err != nil {
        return nil, err
    }

    return &statsJSON, nil
}

// CalculateCPUPercentage calculates CPU usage percentage from stats
func CalculateCPUPercentage(stats *types.StatsJSON) float64 {
    cpuDelta := float64(stats.CPUStats.CPUUsage.TotalUsage - stats.PreCPUStats.CPUUsage.TotalUsage)
    systemDelta := float64(stats.CPUStats.SystemUsage - stats.PreCPUStats.SystemUsage)
    
    if systemDelta > 0.0 && cpuDelta > 0.0 {
        return (cpuDelta / systemDelta) * float64(len(stats.CPUStats.CPUUsage.PercpuUsage)) * 100.0
    }
    return 0.0
}

Step 1.3: Add Dashboard Operation Handler (api/internal/features/dashboard/get_docker_stats.go - new file)

package dashboard

import (
    "github.com/raghavyuva/nixopus-api/internal/features/deploy/docker"
    "github.com/raghavyuva/nixopus-api/internal/features/logger"
)

func (m *DashboardMonitor) GetDockerStats() {
    // Check context cancellation
    select {
    case <-m.ctx.Done():
        return
    default:
    }

    // Get all running containers
    containers, err := m.dockerService.ListAllContainers()
    if err != nil {
        m.BroadcastError(err.Error(), GetDockerStats)
        return
    }

    var dockerStats []DockerStatsData
    
    // Collect stats for each running container
    for _, container := range containers {
        if container.State != "running" {
            continue // Only get stats for running containers
        }

        stats, err := m.dockerService.GetContainerStats(container.ID)
        if err != nil {
            m.log.Log(logger.Warning, "Failed to get stats for container", container.ID)
            continue
        }

        // Calculate metrics
        cpuPercent := docker.CalculateCPUPercentage(stats)
        memUsage := stats.MemoryStats.Usage
        memLimit := stats.MemoryStats.Limit
        memPercent := 0.0
        if memLimit > 0 {
            memPercent = (float64(memUsage) / float64(memLimit)) * 100.0
        }

        // Network stats
        var netRx, netTx uint64
        for _, network := range stats.Networks {
            netRx += network.RxBytes
            netTx += network.TxBytes
        }

        // Block I/O stats
        var blockRead, blockWrite uint64
        for _, blkio := range stats.BlkioStats.IoServiceBytesRecursive {
            if blkio.Op == "Read" {
                blockRead += blkio.Value
            } else if blkio.Op == "Write" {
                blockWrite += blkio.Value
            }
        }

        containerName := container.Names[0]
        if len(containerName) > 0 && containerName[0] == '/' {
            containerName = containerName[1:] // Remove leading slash
        }

        dockerStats = append(dockerStats, DockerStatsData{
            ContainerID:   container.ID[:12], // Short ID
            ContainerName: containerName,
            Stats: ContainerStatsInfo{
                CPUPercentage:    cpuPercent,
                MemoryUsage:      memUsage,
                MemoryLimit:      memLimit,
                MemoryPercentage: memPercent,
                NetworkRx:        netRx,
                NetworkTx:        netTx,
                BlockRead:        blockRead,
                BlockWrite:       blockWrite,
                PIDs:             stats.PidsStats.Current,
            },
            Timestamp: time.Now(),
        })
    }

    m.Broadcast(string(GetDockerStats), dockerStats)
}

Step 1.4: Update Operation Handler (api/internal/features/dashboard/init.go)

func (m *DashboardMonitor) HandleOperation(operation DashboardOperation) {
    switch operation {
    case GetContainers:
        m.GetContainers()
    case GetSystemStats:
        m.GetSystemStats()
    case GetDockerStats:  // NEW
        m.GetDockerStats()
    default:
        m.log.Log(logger.Error, "Unknown operation", string(operation))
    }
}

Phase 2: Frontend Implementation

Step 2.1: Add Types (view/redux/types/monitor.ts)

export interface ContainerStatsInfo {
  cpu_percentage: number;
  memory_usage: number;
  memory_limit: number;
  memory_percentage: number;
  network_rx: number;
  network_tx: number;
  block_read: number;
  block_write: number;
  pids: number;
}

export interface DockerStatsData {
  container_id: string;
  container_name: string;
  stats: ContainerStatsInfo;
  timestamp: string;
}

Step 2.2: Update Monitor Hook (view/app/dashboard/hooks/use-monitor.ts)

const [dockerStats, setDockerStats] = useState<DockerStatsData[]>([]);

// In message handler
else if (parsedMessage.action === 'get_docker_stats' && parsedMessage.data) {
  setDockerStats(parsedMessage.data);
  setLastError(null);
}

// Return dockerStats in the hook return value
return {
  containersData,
  systemStats,
  dockerStats,  // NEW
  // ... rest
};

Step 2.3: Create Docker Stats Widget Component (view/app/dashboard/components/docker-stats/docker-stats-widget.tsx - new file)

'use client';

import React from 'react';
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
import { Activity } from 'lucide-react';
import { DockerStatsData } from '@/redux/types/monitor';
import { TypographySmall } from '@/components/ui/typography';
import { 
  Table, 
  TableBody, 
  TableCell, 
  TableHead, 
  TableHeader, 
  TableRow 
} from '@/components/ui/table';
import { formatBytes } from '@/lib/utils';

interface DockerStatsWidgetProps {
  dockerStats: DockerStatsData[];
}

export function DockerStatsWidget({ dockerStats }: DockerStatsWidgetProps) {
  if (!dockerStats || dockerStats.length === 0) {
    return (
      <Card>
        <CardHeader>
          <CardTitle className="text-xs sm:text-sm font-bold flex items-center">
            <Activity className="h-3 w-3 sm:h-4 sm:w-4 mr-1 sm:mr-2" />
            <TypographySmall>Docker Container Stats</TypographySmall>
          </CardTitle>
        </CardHeader>
        <CardContent>
          <p className="text-sm text-muted-foreground">No running containers</p>
        </CardContent>
      </Card>
    );
  }

  return (
    <Card>
      <CardHeader>
        <CardTitle className="text-xs sm:text-sm font-bold flex items-center">
          <Activity className="h-3 w-3 sm:h-4 sm:w-4 mr-1 sm:mr-2" />
          <TypographySmall>Docker Container Stats</TypographySmall>
        </CardTitle>
      </CardHeader>
      <CardContent>
        <div className="overflow-x-auto">
          <Table>
            <TableHeader>
              <TableRow>
                <TableHead>Container</TableHead>
                <TableHead>CPU %</TableHead>
                <TableHead>Memory</TableHead>
                <TableHead>Net I/O</TableHead>
                <TableHead>Block I/O</TableHead>
              </TableRow>
            </TableHeader>
            <TableBody>
              {dockerStats.map((stat) => (
                <TableRow key={stat.container_id}>
                  <TableCell className="font-medium">
                    {stat.container_name}
                  </TableCell>
                  <TableCell>
                    {stat.stats.cpu_percentage.toFixed(2)}%
                  </TableCell>
                  <TableCell>
                    {formatBytes(stat.stats.memory_usage)} / {formatBytes(stat.stats.memory_limit)}
                    <br />
                    <span className="text-xs text-muted-foreground">
                      ({stat.stats.memory_percentage.toFixed(2)}%)
                    </span>
                  </TableCell>
                  <TableCell>
                    <div className="text-xs">
                      <div>↓ {formatBytes(stat.stats.network_rx)}</div>
                      <div>↑ {formatBytes(stat.stats.network_tx)}</div>
                    </div>
                  </TableCell>
                  <TableCell>
                    <div className="text-xs">
                      <div>R: {formatBytes(stat.stats.block_read)}</div>
                      <div>W: {formatBytes(stat.stats.block_write)}</div>
                    </div>
                  </TableCell>
                </TableRow>
              ))}
            </TableBody>
          </Table>
        </div>
      </CardContent>
    </Card>
  );
}

Step 2.4: Update Dashboard Page (view/app/dashboard/page.tsx)

// Import the new widget
import { DockerStatsWidget } from './components/docker-stats/docker-stats-widget';

// Add to defaultHiddenWidgets (disabled by default per requirements)
const defaultHiddenWidgets = ['clock', 'network', 'docker-stats'];

// Add to allWidgetLabels
const allWidgetLabels = [
  // ... existing widgets
  { id: 'docker-stats', label: 'Docker Stats' }  // NEW
];

// Add to widget definitions in MonitoringSection
const allWidgetDefinitions = [
  // ... existing widgets
  {
    id: 'docker-stats',
    component: <DockerStatsWidget dockerStats={dockerStats} />,
    className: 'md:col-span-2',
    isDefault: false  // Not enabled by default
  }
];

Step 2.5: Update Dashboard Hook (view/app/dashboard/hooks/use-dashboard.ts)

// Destructure dockerStats from useMonitor
const { containersData, systemStats, dockerStats } = useMonitor();

// Return dockerStats
return {
  // ... existing returns
  dockerStats,
};

Step 2.6: Update Monitor Start Configuration (view/app/dashboard/hooks/use-monitor.ts)

// User must explicitly enable docker stats by adding the widget
// When widget is visible, include operation in the request
const startMonitoring = useCallback((includeDockerStats = false) => {
  if (!isReady) return;
  
  const operations = ['get_containers', 'get_system_stats'];
  if (includeDockerStats) {
    operations.push('get_docker_stats');
  }
  
  sendJsonMessage({
    action: 'dashboard_monitor',
    data: {
      interval: 10,
      operations
    }
  });
  setIsMonitoring(true);
}, [isReady, sendJsonMessage]);

Phase 3: Multi-Server Compatibility

Step 3.1: Leverage Existing SSH Tunnel Support

The Docker stats implementation automatically works with multi-server architecture because:

• DockerService already supports SSH-tunneled connections (issue feat: add support for docker over ssh tunnel #549)
• The ContainerStats API call goes through the same DockerService.Cli client
• No additional changes needed - it's distro-agnostic

Step 3.2: Future Enhancement: Server Selection

For full multi-server support (future PR):

// Add server selection to widget
interface DockerStatsWidgetProps {
  dockerStats: DockerStatsData[];
  serverId?: string;  // Optional server ID for multi-server
}

Phase 4: Configuration & Documentation

Step 4.1: Update Feature Documentation

• Document the widget is optional and disabled by default
• Users enable it via "Add Widget" dropdown
• Works with local and remote Docker (SSH tunnel)

Step 4.2: Add Utility Functions (view/lib/utils.ts)

export function formatBytes(bytes: number): string {
  if (bytes === 0) return '0 B';
  const k = 1024;
  const sizes = ['B', 'KB', 'MB', 'GB', 'TB'];
  const i = Math.floor(Math.log(bytes) / Math.log(k));
  return `${(bytes / Math.pow(k, i)).toFixed(2)} ${sizes[i]}`;
}

Phase 5: Testing & Validation

Step 5.1: Backend Testing

• Test stats collection for running containers
• Verify SSH tunnel compatibility
• Test with 0 containers, 1 container, multiple containers
• Validate CPU and memory calculations

Step 5.2: Frontend Testing

• Test widget appears in "Add Widget" dropdown
• Verify widget is hidden by default
• Test enabling/disabling widget
• Test real-time updates
• Test responsive layout

Step 5.3: Cross-Platform Testing

• Test on Ubuntu, Debian, CentOS, Alpine
• Verify Docker SDK compatibility across distros

Key Design Decisions ✅

1. Optional by Default: Widget in defaultHiddenWidgets array
2. Distro-Agnostic: Uses Docker SDK API calls (works everywhere Docker runs)
3. Multi-Server Ready: Leverages existing SSH tunnel infrastructure from feat: add support for docker over ssh tunnel #549
4. Performance: Only fetches stats for running containers
5. Extensibility: Easy to add per-server filtering later

Estimated Effort

• Backend: ~4-6 hours
• Frontend: ~3-4 hours
• Testing: ~2-3 hours
• Total: 9-13 hours

Would you like me to help with implementing any specific phase, or would you like to create sub-issues for tracking each phase?

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash

# First, let's get details about issue #549 for multi-server context
echo "=== Issue #549 Details ==="
gh issue view 549 --json title,body,comments --jq '.title, .body, (.comments[] | "Comment by " + .author.login + ": " + .body)'

echo -e "\n=== Project Structure ==="
fd -t f -e py -e js -e ts -e jsx -e tsx -e vue -e svelte | head -30

echo -e "\n=== Finding Dashboard Files ==="
fd -i dashboard

echo -e "\n=== Finding Widget Files ==="
fd -i widget

echo -e "\n=== Finding Docker Related Files ==="
fd -i docker

echo -e "\n=== Finding Configuration Files ==="
fd -e yaml -e yml -e json -e toml -e ini | grep -E "(config|settings)" | head -20

Length of output: 18963

---

🏁 Script executed:

#!/bin/bash

# Search for dashboard implementations
echo "=== Dashboard Implementation Search ==="
rg -n -C3 "class.*Dashboard|def.*dashboard" --type=py

echo -e "\n=== Widget Pattern Search ==="
rg -n -C3 "class.*Widget|def.*widget" --type=py

echo -e "\n=== Docker Stats or Metrics Search ==="
rg -n -C3 "docker.*stats|container.*stats" -i

echo -e "\n=== Configuration Pattern Search ==="
rg -n -C3 "enable|disabled|optional.*widget" --type=py | head -40

Length of output: 5632

---

🏁 Script executed:

#!/bin/bash

# Let's look at the main application structure
echo "=== Main Application Files ==="
fd -t f "main.py|app.py|__init__.py" | head -10

echo -e "\n=== Package Structure ==="
ls -la

echo -e "\n=== README Content ==="
cat README.md 2>/dev/null || echo "No README.md found"

echo -e "\n=== Setup or Requirements Files ==="
fd -t f "requirements|setup.py|pyproject.toml|package.json"

Length of output: 6432

---

🏁 Script executed:

#!/bin/bash

# Look at the dashboard structure and components
echo "=== Dashboard Directory Structure ==="
fd . view/app/dashboard -t f

echo -e "\n=== Dashboard TypeScript Files ==="
cat view/app/dashboard/page.tsx 2>/dev/null || echo "page.tsx not found"

echo -e "\n=== Widget Selector Component ==="
cat view/app/dashboard/components/widget-selector.tsx

echo -e "\n=== Containers Widget Implementation ==="
cat view/app/dashboard/components/containers/containers-widget.tsx

Length of output: 13855

---

🏁 Script executed:

#!/bin/bash

# Look at monitor types and system stats
echo "=== Monitor Types Definition ==="
cat view/redux/types/monitor.ts 2>/dev/null || echo "monitor types not found"

echo -e "\n=== Monitor Hook Implementation ==="
cat view/app/dashboard/hooks/use-monitor.ts

echo -e "\n=== Dashboard Hook Implementation ==="
cat view/app/dashboard/hooks/use-dashboard.ts

Length of output: 7836

---

🏁 Script executed:

#!/bin/bash

# Look at the backend monitoring implementation
echo "=== Dashboard Monitor Go Implementation ==="
cat api/internal/realtime/dashboard_monitor.go

echo -e "\n=== Container Types ==="
cat api/internal/features/container/types/container_types.go | head -100

Length of output: 5998

---

🏁 Script executed:

#!/bin/bash

# Look at Docker service implementation
echo "=== Docker Service Files ==="
fd . api/internal/features/deploy/docker -t f

echo -e "\n=== Docker Init/Service File ==="
cat api/internal/features/deploy/docker/init.go 2>/dev/null || echo "init.go not found"

echo -e "\n=== Docker Stats Collection (if exists) ==="
rg -n "Stats|stats" api/internal/features/deploy/docker/ -A5 -B5 | head -50

Length of output: 16236

---

🏁 Script executed:

#!/bin/bash

# Look for configuration patterns
echo "=== Feature Flags or Configuration ==="
rg -n "feature.*flag|config.*widget|dashboard.*config" -i --type=ts | head -40

echo -e "\n=== User Settings or Preferences ==="
rg -n "user.*preference|user.*setting|widget.*config" -i --type=ts | head -40

Length of output: 7852

---

🏁 Script executed:

#!/bin/bash

# Check for multi-server related code
echo "=== Multi-Server Architecture ==="
rg -n "multi.*server|server.*list|remote.*server" -i | head -40

echo -e "\n=== Server Models ==="
fd -e go | xargs rg -l "type.*Server.*struct" | head -10

Length of output: 168353

---

🏁 Script executed:

#!/bin/bash

# Look at how feature flags work
echo "=== Feature Flag Implementation ==="
cat api/internal/features/feature-flags/controller/controller.go 2>/dev/null || echo "controller.go not found"

echo -e "\n=== Feature Flag Types ==="
rg -n "FeatureName|feature.*name" api/internal/features/feature-flags/ -A3 -B3 | head -60

echo -e "\n=== Dashboard Monitor Operations ==="
cat api/internal/features/dashboard/types.go 2>/dev/null || echo "types.go not found in dashboard"

Length of output: 8763

---

🏁 Script executed:

#!/bin/bash

# Look at Docker client stats API usage
echo "=== Docker Stats API Usage ==="
rg -n "ContainerStats|docker.*stats" api/ -A5 -B5 | head -80

echo -e "\n=== Dashboard Service Files ==="
fd . api/internal/features/dashboard -t f

echo -e "\n=== Dashboard Service Implementation ==="
cat api/internal/features/dashboard/monitor.go 2>/dev/null || echo "monitor.go not found"

Length of output: 1326

---

🏁 Script executed:

#!/bin/bash

# Look at the feature flag names enum
echo "=== Feature Flag Names ==="
cat view/types/feature-flags.ts

echo -e "\n=== Feature Flag Usage in Dashboard ==="
rg -n "FeatureNames|isFeatureEnabled" view/app/dashboard/ -A2 -B2

Length of output: 2696

---

🏁 Script executed:

#!/bin/bash

# Look at SSH tunnel implementation for multi-server
echo "=== SSH Tunnel Implementation ==="
cat api/internal/features/deploy/docker/cluster.go 2>/dev/null | head -100

echo -e "\n=== Docker Service Structure ==="
rg -n "type.*DockerService|type.*DockerRepository" api/internal/features/deploy/docker/init.go -A10 | head -50

Length of output: 3744

---

🏁 Script executed:

#!/bin/bash

# Check for any existing stats collection
echo "=== System Stats Collection ==="
cat api/internal/features/dashboard/system_stats.go | head -150

echo -e "\n=== Container Service ==="
ls -la api/internal/features/container/
fd . api/internal/features/container/service -t f

Length of output: 4455

---

🏁 Script executed:

#!/bin/bash

# Look at feature flags database schema
echo "=== Feature Flags Schema ==="
cat api/internal/types/feature_flags.go 2>/dev/null || echo "feature_flags.go not found"

echo -e "\n=== Database Migrations for Features ==="
fd . api/migrations -t f | grep -i "feature\|dashboard" | head -10

echo -e "\n=== Check existing Docker container stats implementation ==="
rg -n "Stats.*Container|ContainerStats" api/internal/features/container/ -A5 | head -40

Length of output: 2902

---

🏁 Script executed:

#!/bin/bash

# Look at how widgets are stored/configured
echo "=== Widget Configuration in Frontend ==="
cat view/app/dashboard/page.tsx | grep -A10 -B10 "defaultHiddenWidgets\|hiddenWidgets"

echo -e "\n=== Dashboard Init and Broadcast ==="
cat api/internal/features/dashboard/init.go
cat api/internal/features/dashboard/broadcast.go

Length of output: 8151

---

🏁 Script executed:

#!/bin/bash

# Check for Docker Stats API in Go client
echo "=== Docker Client Stats Methods ==="
rg -n "Cli\.ContainerStats|docker.*Client.*Stats" api/ -A3 -B3 | head -50

echo -e "\n=== Container Get Implementation ==="
cat api/internal/features/dashboard/get_containers.go

Length of output: 636

---

🏁 Script executed:

#!/bin/bash

# Feature flags types and enums
echo "=== Feature Flags Backend Types ==="
cat api/internal/types/feature_flags.go 2>/dev/null || cat api/internal/features/feature-flags/types.go 2>/dev/null || echo "Looking for feature flag types..."

fd feature_flag api/internal/types -t f
fd types.go api/internal/features/feature-flags -t f

Length of output: 1753

---

🏁 Script executed:

#!/bin/bash

# Complete understanding of the architecture
echo "=== Types Directory Structure ==="
ls -la api/internal/types/

echo -e "\n=== Feature Flags Type Definition ==="
cat api/internal/types/types.go | grep -A20 "FeatureName\|FeatureFlag"

Length of output: 1082

---

@raghavyuva

Here’s a concrete, phased action plan to add a Docker stats widget that’s optional (disabled by default), distro‑agnostic, and ready for multi‑server based on #549.

Executive summary

• We’ll add a new “Docker Stats” widget that surfaces live per‑container CPU, memory, and IO metrics.
• It will be hidden by default and user‑opt‑in via the existing WidgetSelector.
• Backend will stream a new WebSocket operation get_container_stats that uses the Docker API (distro‑agnostic).
• For multi‑server, we’ll reuse the SSH approach from feat: add support for docker over ssh tunnel #549: when a server is selected, we create/use a per‑server Docker client (via SSH tunnel or DOCKER_HOST) and stream that server’s stats.

Phase 0 — Groundwork (no user‑visible change)

1. Backend: introduce stat operation/type plumbing

• Files to add/change:

  • api/internal/features/dashboard/types.go
    • Add a new DashboardOperation: GetContainerStats = "get_container_stats".
    • Decision: Keep AllOperations as-is for now; we’ll explicitly opt-in this op from the client. This avoids unnecessary server work when the widget is hidden.
  • api/internal/features/dashboard/get_container_stats.go (new)
    • Implement func (m *DashboardMonitor) GetContainerStats().
    • Steps:
      • List containers via m.dockerService.ListAllContainers().
      • For each container (limit N=10 initially, configurable), call Docker API stats with stream=false.
      • Compute CPU% using standard Docker formula, memory usage/limit/percent, network and block IO (map to api/internal/features/container/types.ContainerStats).
      • Build a compact payload: [{id,name,cpu_pct,mem_usage,mem_limit,mem_pct,net_rx,net_tx,blk_read,blk_write,status,image,started_at?}].
      • Broadcast with action "get_container_stats".
  • api/internal/realtime/dashboard_monitor.go
    • In HandleOperation, add a case for GetContainerStats calling m.GetContainerStats().

• Performance and safety:

  • Timeouts: per-container stats request should use a short context timeout (e.g., 750ms) so a stalled container doesn’t block the loop.
  • Concurrency: fan-out stats pulls with a worker pool size min(len(containers), 5) to keep request bursts bounded.
  • Truncation: cap to the top N by most recently started or by CPU usage (we can sort client-side after payload).

2. Backend: Docker client configurability (multi‑server ready)

• api/internal/features/deploy/docker/init.go
  • Add NewDockerClientWithHost(host string) and NewDockerServiceWithHost(host string).
  • Important fix: NewDockerClient() currently prefers unix:///var/run/docker.sock even if DOCKER_HOST is set. For multi‑server, prefer client.FromEnv first, falling back to unix socket.
• api/internal/features/dashboard/init.go
  • NewDashboardMonitor: accept an optional targetHost (or tunnel path) and construct dockerService accordingly (default local if none).

3. Backend: SSH tunnel hook (reference feat: add support for docker over ssh tunnel #549)

• Reuse the SSH groundwork from feat: add support for docker over ssh tunnel #549: if the WS message includes a target server, create an SSH tunnel to that server’s /var/run/docker.sock and pass the resulting local unix:// path into NewDockerServiceWithHost().
• If tunnel support isn’t in the current ssh package, add an sshpkg method (e.g., CreateDockerTunnel(server) -> returns localSocketPath, closeFunc). Document that this is the bridge for multi‑server.

Phase 1 — Frontend widget (hidden by default, user‑opt‑in)

1. Types and hooks

• view/redux/types/monitor.ts
  • Add a type for container stats:
    • export interface ContainerLiveStats { id: string; name: string; cpuPct: number; memUsage: number; memLimit: number; memPct: number; netRx: number; netTx: number; blkRead: number; blkWrite: number; image: string; status: string; }
• view/app/dashboard/hooks/use-monitor.ts
  • Extend operations sent on startMonitoring to include 'get_container_stats' only when the widget is visible (see next bullet).
  • Extend message handler to set a new piece of state: const [containerStats, setContainerStats] = useState<ContainerLiveStats[]>([]); and update it on action === 'get_container_stats'.
  • Note: Today this hook is unaware of which widgets are visible. To avoid a larger refactor, we’ll:
    • Add an optional parameter to use_monitor({ operationsOverride?: string[] }) and pass the desired operations from the Dashboard page based on hiddenWidgets.
    • If no override is provided, use existing defaults ['get_containers', 'get_system_stats'].

2. Wire widget visibility to operations

• view/app/dashboard/page.tsx
  • defaultHiddenWidgets: append 'docker-stats'.
  • allWidgetLabels: add { id: 'docker-stats', label: 'Docker Stats' }.
  • allWidgetDefinitions: add the component definition with isDefault: false.
  • Instantiate useMonitor with operationsOverride built from visible widgets:
    • Always include get_containers and get_system_stats.
    • Include get_container_stats only when 'docker-stats' is not hidden.

3. Widget UI

• view/app/dashboard/components/docker/docker-stats-widget.tsx (new)
  • Display a table or list of up to N containers sorted by cpuPct desc. Columns: Name, CPU%, Mem (used/limit, %), Net IO (rx/tx), Block IO (r/w), Status, Image.
  • Provide a link/button to “View all containers” (routes to /containers).
  • Respect the dashboard’s delete (hide) action and grid sizing.
• Minimal integration:
  • In page.tsx allWidgetDefinitions add:
    • { id: 'docker-stats', component: , className: 'md:col-span-2', isDefault: false }.

Phase 2 — Multi‑server selection (align with #549)

1. Client target server

• Decide the UX for picking a server context (topbar dropdown, similar to team/org switcher). For a first iteration, reuse any existing server selection state if present; if not, add a simple “Server” dropdown in view/components/layout/topbar-widgets.tsx that sets localStorage 'dashboard-server' and provides it via context.
• When starting monitoring, include the server identifier in the WS payload:
  • sendJsonMessage({ action: 'dashboard_monitor', data: { interval: 10, operations: [...], server: { host, port?, user? } } });

2. Server uses target

• api/internal/realtime/dashboard_monitor.go handleDashboardMonitor:
  • If msg.Data.server is provided, resolve/prepare a docker client for that target:
    • Either set up SSH tunnel and use unix:// local socket path, or populate DOCKER_HOST and create a client with FromEnv.
  • Use UpdateConfig (add a new branch) to prevent spinning multiple Start goroutines when updates arrive. If we keep the same action, change handleDashboardMonitor to call monitor.UpdateConfig(config) if the monitor already exists, not Start() again.

3. Lifecycles

• Ensure monitor.Close() tears down ssh tunnel (closeFunc) and removes local socket file if we create one.
• Keep interval configurable as it is today.

Phase 3 — Hardening and docs

1. Tests

• Backend unit tests:
  • CPU% math from docker stats JSON.
  • Worker pool timeout behavior.
  • With and without target server (mock ssh tunnel to return a fake unix path).
• E2E smoke:
  • WebSocket start → receive 'get_container_stats' payload within 2 intervals.
• Frontend:
  • Render widget hidden by default; appears via WidgetSelector and persists across reloads.
  • Table sorts by CPU%.

2. Docs and examples

• Update docs/blog and README monitoring section with: how to enable the widget and optional multi‑server target selection.
• Note resource impact and how to change interval.

3. Security and permissions

• Dashboard remains gated by FeatureNames.FeatureMonitoring (already in use-dashboard.ts).
• No new RBAC scope is strictly required, but if desired we can add “monitor:read:stats” later.

Proposed code scaffolds (illustrative, not a commit)

• Backend: new op and handler stub

// api/internal/features/dashboard/types.go
const (
  GetContainers     DashboardOperation = "get_containers"
  GetSystemStats    DashboardOperation = "get_system_stats"
  GetContainerStats DashboardOperation = "get_container_stats"
)
// keep AllOperations unchanged to avoid default enabling

// api/internal/features/dashboard/get_container_stats.go
func (m *DashboardMonitor) GetContainerStats() {
  ctx, cancel := context.WithTimeout(m.ctx, 3*time.Second)
  defer cancel()

  containers, err := m.dockerService.ListAllContainers()
  if err != nil {
    m.BroadcastError(err.Error(), GetContainerStats)
    return
  }
  // limit and fan-out workers...
  // build []types.ContainerStats (map to your public payload) and:
  m.Broadcast(string(GetContainerStats), payload)
}

• Frontend: TS types

// view/redux/types/monitor.ts
export interface ContainerLiveStats {
  id: string; name: string;
  cpuPct: number;
  memUsage: number; memLimit: number; memPct: number;
  netRx: number; netTx: number;
  blkRead: number; blkWrite: number;
  image: string; status: string;
}

• Frontend: hook opt-in via visible widgets

// view/app/dashboard/hooks/use-monitor.ts
function use_monitor(opts?: { operationsOverride?: string[] }) {
  const ops = opts?.operationsOverride ?? ['get_containers', 'get_system_stats'];
  // when starting:
  sendJsonMessage({ action: 'dashboard_monitor', data: { interval: 10, operations: ops } });
  // handle 'get_container_stats' by setContainerStats(...)
}

• Frontend: page builds the operations based on hidden widgets

// view/app/dashboard/page.tsx
const baseOps = ['get_containers', 'get_system_stats'] as string[];
const ops = hiddenWidgets.includes('docker-stats')
  ? baseOps
  : [...baseOps, 'get_container_stats'];
const { containersData, systemStats, containerStats } = useMonitor({ operationsOverride: ops });

• Frontend: widget stub

// view/app/dashboard/components/docker/docker-stats-widget.tsx
'use client';
import { ContainerLiveStats } from '@/redux/types/monitor';
export default function DockerStatsWidget({ stats }: { stats: ContainerLiveStats[] }) {
  // Render table sorted by cpuPct desc, provide link to /containers
  return <YourTable rows={stats} />;
}

Multi‑server alignment details (ties to #549)

• Where we will hook it in:
  • On the client, include an optional server field when starting monitoring.
  • On the server, if server is present:
    • Either set up an SSH tunnel to remote /var/run/docker.sock (recommended, per feat: add support for docker over ssh tunnel #549 direction) and create a Docker client with client.WithHost("unix:///path/to/tunnel.sock");
    • Or set DOCKER_HOST=ssh://user@host and use client.FromEnv. The tunnel approach tends to be more predictable and avoids needing the experimental SSH transport in Docker client builds.
• Cleanup is handled in monitor.Close() so tunnel file descriptors and sockets are not leaked.
• This keeps the implementation distro‑agnostic (it talks to Docker Engine API over a socket/tunnel; no host‑specific commands).

Acceptance criteria

• The “Docker Stats” widget is hidden by default and can be added via WidgetSelector.
• When visible, it shows live stats for up to 10 containers, refreshing roughly every 10 seconds.
• No noticeable UI stutter; backend caps stats collection time and parallelism.
• If a target server is selected (Phase 2), the stats reflect that server; switching servers updates results within one interval.
• Works on any Linux distro that runs Docker Engine; no shell commands are used for stats (only Docker API).

Risks and mitigations

• Stats calls can be heavy on hosts with many containers: mitigate with a limit and a worker pool; later, add pagination or “top N by CPU”.
• WS handler currently restarts a monitor goroutine on each config message (potential duplication). Proposed fix: use UpdateConfig() for updates instead of Start() if a monitor exists.
• Docker client host selection: switch to prefer FromEnv first, then unix socket; add explicit WithHost overloads.

Estimated effort

• Phase 0 (backend plumbing and stats): 1–2 days including tests.
• Phase 1 (frontend widget + wiring): 1 day.
• Phase 2 (multi‑server target + tunnel lifecycle): 2–3 days depending on SSH tunnel helper maturity.

Feature request issue (ready to open; follows your template)
Title
feat: add optional Docker Stats widget to dashboard (disabled by default)

Body

• Link to related issue(s):
  • feat: add support for docker over ssh tunnel #549 (SSH tunneling for Docker; multi‑server groundwork)
• Description
  • Add a new dashboard widget “Docker Stats” that shows live per‑container CPU, memory, network, and block IO. The widget is hidden by default and users can add it via “Add Widget”.
  • Backend streams a new WS operation get_container_stats using Docker Engine API; distro‑agnostic by design.
  • Multi‑server ready: when a server is selected, stats are fetched via an SSH tunnel to that server’s Docker socket.
• Scope of Change
  • View (UI/UX)
  • API (WS operation + payload)
  • CLI
  • Infra / Deployment (SSH tunnel lifecycle for remote Docker)
  • Docs
• Screenshot / Video / GIF (if applicable)
  • [placeholder]
• Related PRs
  • feat: add support for docker over ssh tunnel #549 reference for SSH tunnel design
• Additional Notes for Reviewers
  • Widget is hidden by default via defaultHiddenWidgets and exposed in WidgetSelector.
  • Worker pool + timeouts protect the Docker stats loop on large hosts.
• Developer Checklist
  • Tests for CPU% math and WS flow
  • Docs updated (Monitoring + Dashboard customization)
  • No secrets exposed; tunnel closes on Stop()
  • Feature flags remain unchanged (gated by monitoring)
• Reviewer Checklist
  • Verified WS messages include new action
  • Confirmed widget is not visible by default
  • Verified stats reflect selected server (Phase 2)

Would you like me to open this feature request issue and bootstrap the task list as above? If yes, I’ll create it and assign it to you, and I can also break Phases 0–2 into sub‑tasks.