nuc/.artifacts/2026-02-06_17-30_deployment-dashboard-design.md

# NUC Portal - Deployment Dashboard Design

**Date:** 2026-02-06 17:30
**Context:** Reverse-engineered Vercel deployment dashboard to design similar feature for nuc-portal

## Task Summary

**Goal:** Add deployment detail page to nuc-portal
- Current: Click row in Deployments tab → expand/collapse logs inline
- New: Click row → navigate to `/deployments/[uuid]` dashboard page
- Keep: Add explicit expand button for inline log preview

## Vercel Dashboard Structure (Reference)

### Page Layout
```
Breadcrumb: Deployments > [deployment-id]
Tabs: Deployment | Logs | Resources | Source | Open Graph
Actions: Share | Logs | Visit
```

### Deployment Tab Sections

**1. Deployment Details Card (Top)**
| Left | Right |
|------|-------|
| Preview screenshot | Created: user + date |
| | Status: Ready + "Latest" badge |
| | Duration: 43s + "43d ago" |
| | Environment: Production + "Current" |
| | Domains: list with "+N" overflow |
| | Source: branch + commit hash + message |

**2. Collapsible Sections:**

| Section | Content |
|---------|---------|
| **Deployment Settings** | Recommendations cards, Build Settings (concurrent builds, machine specs, prioritize prod), Runtime Settings (fluid compute, function CPU, Node version, protections) |
| **Build Logs** | Header: line count, warnings, search. Body: timestamped log lines, warnings highlighted yellow |
| **Deployment Summary** | Framework badge, Edge Middleware count, Static Assets (filterable by type), Functions, ISR Functions, Cron Jobs |
| **Deployment Checks** | External check integrations or "No checks configured" |
| **Assigning Custom Domains** | Domain list with status checkmarks and manage links |

**3. Bottom Cards (4-column grid):**
- Runtime Logs | Observability | Speed Insights | BotID

---

## Coolify Data Available

### From Deployment Table
```typescript
interface CoolifyDeployment {
  deployment_uuid: string;
  application_id: string;
  application_name: string;
  server_name: string;
  status: 'finished' | 'error' | 'in_progress' | 'queued' | 'cancelled';
  commit: string;           // SHA
  commit_message: string;   // Full message
  is_webhook: boolean;
  is_api: boolean;
  force_rebuild: boolean;
  rollback: boolean;
  created_at: string;
  updated_at: string;
  finished_at: string | null;
  logs: DeploymentLog[];    // JSON array with timestamps
  deployment_url: string;   // Coolify UI link
}
```

### From Application Table
```typescript
interface CoolifyApp {
  uuid: string;
  name: string;
  fqdn: string;             // e.g., "http://nuc.lan"
  status: string;           // e.g., "running:unknown"
  git_repository: string;
  git_branch: string;
  build_pack: string;       // nixpacks, dockerfile, etc.
  ports_exposes: string;
  created_at: string;
  updated_at: string;
}
```

### Direct Database Query (via tinker)
```bash
ssh nuc "docker exec coolify php artisan tinker --execute=\"
use App\\\\Models\\\\Application;
use App\\\\Models\\\\ApplicationDeploymentQueue;
\\\$app = Application::where('uuid', '<uuid>')->first();
\\\$d = ApplicationDeploymentQueue::where('application_id', \\\$app->id)->latest()->first();
echo json_encode(\\\$d->toArray(), JSON_PRETTY_PRINT);
\""
```

---

## Gap Analysis

### What Coolify Provides (Direct Mapping)
- Deployment UUID, status, timestamps, duration (computed)
- Git branch, commit SHA, commit message
- Build logs with timestamps
- App name, FQDN/domains, build pack, ports
- Webhook/API trigger info

### Gaps - Ranked by Priority

**Tier 1 - High Impact, Easy**
1. **Healthcheck Status** - Docker API: `docker inspect --format='{{.State.Health.Status}}'`
2. **Container Metrics** - Docker stats: CPU%, Memory usage
3. **Environment Label** - Parse from Coolify project/environment structure

**Tier 2 - High Impact, Medium Effort**
4. **Preview Screenshot** - Playwright screenshot service triggered on deploy success
5. **Runtime Logs Link** - Deep link to Dozzle: `http://dozzle.nuc.lan/container/<name>`
6. **Rollback Button** - Coolify API supports rollback

**Tier 3 - Nice to Have**
7. **Build Cache Status** - Parse "Restored build cache" from logs
8. **Image Size** - `docker images --format` after build
9. **Uptime Since Deploy** - Container start time from Docker

**Tier 4 - Future**
10. **Response Time** - Uptime Kuma integration
11. **Error Rate** - Log parsing or APM
12. **Git Diff Link** - Construct Gitea compare URL

---

## Proposed Implementation

### Route Structure
```
/deployments/[uuid]     → Deployment dashboard page
```

### UI Changes to Deployments Table
- Add expand/collapse button (chevron icon) on each row
- Row click → navigate to dashboard
- Button click → expand logs inline (current behavior)

### Dashboard Page Sections (Simplified for Coolify)

```
┌─────────────────────────────────────────────────────────┐
│ ← Back to Deployments          rok0w0gg      [Actions]  │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌──────────┐  Created: alezmad · Feb 6, 2026          │
│  │ Preview  │  Status: ● Ready   Health: ● Healthy     │
│  │ or Icon  │  Duration: 2m 51s · 2h ago               │
│  └──────────┘  Environment: production                  │
│                                                         │
│  Domains: http://nuc.lan                               │
│  Source: main · f7c57ca · "Use domain-based URLs..."   │
├─────────────────────────────────────────────────────────┤
│ ▼ Build Logs                              43s  ⚠2  ✓   │
│   [Timestamped log content...]                         │
├─────────────────────────────────────────────────────────┤
│ ▶ Container Info                                        │
│   Build: nixpacks · Ports: 3000                        │
│   CPU: 2.3% · Memory: 156MB                            │
├─────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐        │
│ │ Runtime     │ │ Redeploy    │ │ Rollback    │        │
│ │ Logs →      │ │             │ │             │        │
│ └─────────────┘ └─────────────┘ └─────────────┘        │
└─────────────────────────────────────────────────────────┘
```

### API Endpoints Needed

```typescript
// Existing (nuc-portal)
GET /api/deployments              // List all
GET /api/deployments/[uuid]       // Get one with logs

// New endpoints
GET /api/deployments/[uuid]/health    // Container healthcheck
GET /api/deployments/[uuid]/stats     // CPU/Memory from docker stats
POST /api/deployments/[uuid]/rollback // Trigger rollback
```

### Docker Commands for New Features

```bash
# Healthcheck status
docker inspect --format='{{.State.Health.Status}}' <container>

# Container stats (one-shot)
docker stats --no-stream --format='{{.CPUPerc}},{{.MemUsage}}' <container>

# Container start time (for uptime)
docker inspect --format='{{.State.StartedAt}}' <container>
```

---

## Files to Modify

```
nuc-portal/
├── src/app/deployments/[uuid]/page.tsx   # NEW - Dashboard page
├── src/components/DeploymentsTable.tsx   # Add expand button, row click nav
├── src/components/DeploymentDashboard.tsx # NEW - Dashboard component
├── src/app/api/deployments/[uuid]/
│   ├── route.ts                          # Existing - add more fields
│   ├── health/route.ts                   # NEW - healthcheck endpoint
│   └── stats/route.ts                    # NEW - container stats
└── src/lib/docker.ts                     # NEW - Docker API helpers
```

---

## Implementation Order

### Phase 1: Basic Dashboard (MVP)
1. Create `/deployments/[uuid]` route and page
2. Add expand button to table rows
3. Make row click navigate to dashboard
4. Display existing deployment data in dashboard layout

### Phase 2: Enhanced Data (Tier 1 gaps)
5. Add healthcheck status endpoint
6. Add container metrics endpoint
7. Add environment label parsing

### Phase 3: Actions & Links (Tier 2 gaps)
8. Add Dozzle deep link
9. Add rollback button
10. (Optional) Screenshot service

---

## Related Documentation

- Coolify API: `http://192.168.1.3:8000/api/v1/`
- Existing nuc-portal code: `/Users/agutierrez/Desktop/nuc/nuc-portal/`
- Deployment types: `nuc-portal/src/lib/deployments.ts`
- Coolify helpers: `nuc-portal/src/lib/coolify.ts`