Web UI

The Portoser Web UI provides a visual interface for managing your entire cluster, making it easy to deploy, monitor, and manage services without using the command line.

Drag a service onto another machine. The deployment panel stages a plan; clicking Deploy runs it via SSH.

Overview

Access the Web UI at:

The Web UI offers:

  • Visual cluster overview
  • Drag-and-drop service management
  • Real-time health monitoring
  • Deployment controls
  • Metrics dashboards
  • Service dependency graphs

Features

1. Cluster Dashboard

The main dashboard shows:

  • All Machines: Cards for each machine showing:

    • Machine name and host
    • Number of services running
    • CPU and memory usage
    • Health status
    • Available actions

  • All Services: Cards for each service showing:

    • Service name and type
    • Current machine
    • Health status
    • Uptime
    • Quick actions (start, stop, restart, logs)

2. Drag-and-Drop Deployment

Move services between machines visually:

  1. Drag a service card
  2. Drop it on a target machine
  3. Confirm the deployment
  4. Portoser automatically:
    • Stops the service on the old machine
    • Deploys to the new machine
    • Updates the registry
    • Verifies health

3. Service Management

Each service card provides:

Quick Actions Menu (right-click)

  • Start: Start the service
  • Stop: Stop the service
  • Restart: Restart the service
  • Deploy: Re-deploy the service
  • View Logs: Open log viewer
  • Health Check: Run health check
  • Edit Config: Modify service settings
  • Remove: Remove from registry

Service Details Panel

  • Service configuration
  • Environment variables
  • Health check settings
  • Dependencies
  • Deployment history
  • Metrics graphs

4. Health Monitoring

The Health Dashboard surfaces problem frequency from the knowledge base alongside live status counters.

Real-time health indicators:

  • Green: Service is healthy
  • Yellow: Service is degraded
  • Red: Service is unhealthy
  • Gray: Service is stopped

Health Dashboard

  • Current status of all services
  • Health history timeline
  • Failed health checks
  • Response time graphs
  • Uptime percentages

5. Metrics Dashboard

Live CPU, memory, and disk metrics across every machine, refreshed via WebSocket.

View performance metrics:

System Metrics

  • CPU usage per machine
  • Memory consumption
  • Disk utilization
  • Network traffic

Service Metrics

  • Request rates
  • Response times
  • Error rates
  • Resource usage

Custom Metrics

Configure custom metrics in your service:

services:
  my-app:
    metrics:
      endpoint: "/metrics"
      type: "prometheus"

6. Deployment Panel

Intelligent deployment interface:

  1. Select Service: Choose service to deploy
  2. Select Machine: Choose target machine (or drag-and-drop)
  3. Deployment Options:
    • Intelligent mode (auto-fixing)
    • Force deployment
    • Dry run
  4. Deploy: Start deployment
  5. Watch Progress: Real-time deployment logs
  6. Verify: Automatic health check after deployment

7. Service Registration

Add new services via form:

  1. Click "Add Service" button
  2. Fill in details:
    • Service name
    • Service type (Docker, Local, Native)
    • Path to service
    • Target machine
    • Health check configuration
    • Environment variables
    • Vault secrets
  3. Validate: Form validates inputs
  4. Save: Service added to registry

8. Machine Management

Manage machines in your cluster:

Add Machine

  1. Click "Add Machine"
  2. Enter:
    • Machine name
    • Host (IP or hostname)
    • SSH user
    • Platform (macOS, Linux, BSD)
    • Vault role (optional)
  3. Test Connection: Verify SSH works
  4. Save: Machine added to registry

Machine Details

  • View all services on a machine
  • Bulk operations (start all, stop all, restart all)
  • System resource usage
  • Machine status
  • SSH connection test

9. Dependency Graph

The Service Dependencies page renders the full graph with hierarchical layout, search, and per-node health colour.

Visualize service dependencies:

  • Nodes: Services as circles
  • Edges: Dependencies as arrows
  • Colors: Health status
  • Interactive: Click to view details
  • Layout: Auto-arrange for clarity

Helps understand:

  • Service relationships
  • Impact of failures
  • Deployment order
  • Circular dependencies

10. Deployment History

Track all deployments:

  • Timeline: Chronological deployment list
  • Filters: By service, machine, date, status
  • Details: View deployment logs
  • Rollback: Revert to previous version
  • Compare: Diff between versions

11. Knowledge Base

Browse playbooks generated from past incidents — each carries occurrence counts and success rates.

View learned solutions:

  • Solution Patterns: Auto-fixing patterns
  • Success Rates: How often solutions work
  • Recent Issues: Recently detected problems
  • Playbooks: Documented procedures

12. Vault Management

Manage secrets (requires permissions):

  • List Secrets: View all secrets by service
  • Add Secret: Create new secret
  • Update Secret: Change secret value
  • Delete Secret: Remove secret
  • Audit Log: See who accessed what

Navigation

Main Menu

  • Dashboard: Cluster overview
  • Services: All services
  • Machines: All machines
  • Deploy: Deployment panel
  • Health: Health monitoring
  • Metrics: Performance metrics
  • Dependencies: Dependency graph
  • History: Deployment history
  • Knowledge: Knowledge base
  • Vault: Secret management
  • Settings: User preferences

Keyboard Shortcuts

  • Ctrl+K / Cmd+K: Quick search
  • Ctrl+D / Cmd+D: Deploy selected service
  • Ctrl+H / Cmd+H: View health
  • Ctrl+L / Cmd+L: View logs
  • Ctrl+R / Cmd+R: Restart selected service
  • ?: Show all shortcuts

Real-Time Updates

The UI updates automatically via WebSocket:

  • Service Status: Updates every 5 seconds
  • Health Checks: Updates on check completion
  • Deployments: Live deployment logs
  • Metrics: Updates every 10 seconds

Customization

Theme

Choose between light and dark themes:

  1. Click profile icon
  2. Select "Theme"
  3. Choose Light or Dark

Dashboard Layout

Customize dashboard:

  1. Click "Customize" button
  2. Drag panels to reorder
  3. Toggle panel visibility
  4. Resize panels
  5. Save layout

Metrics Period

Change metrics time range:

  • Last hour
  • Last 24 hours
  • Last 7 days
  • Last 30 days
  • Custom range

Authentication

Login

If authentication is enabled:

  1. Navigate to Web UI
  2. Enter username and password
  3. Optional: Enable 2FA
  4. Click "Login"

Keycloak Integration

If using Keycloak:

  1. Click "Login with Keycloak"
  2. Redirects to Keycloak
  3. Authenticate
  4. Redirected back to UI

mTLS

For production, enable mTLS:

  1. Generate client certificates
  2. Configure in browser
  3. Portoser validates certificate
  4. Access granted

Mobile Support

The Web UI is responsive and works on:

  • Desktop (optimized)
  • Tablets (good)
  • Mobile phones (basic functionality)

Mobile features:

  • Touch-friendly buttons
  • Simplified layout
  • Swipe gestures
  • Mobile-optimized menus

Installation

Using Docker Compose

cd web
cp .env.example .env
# Edit .env with your settings
docker-compose up -d

Access at http://localhost:8080

Manual Installation

Backend

cd web/backend
uv sync
uv run uvicorn main:app --host 0.0.0.0 --port 8000

Frontend

cd web/frontend
npm install
npm run build
npm run preview

Access at http://localhost:4173

Configuration

Environment Variables

Edit web/.env:

# Backend
BACKEND_PORT=8000
CORS_ORIGINS=http://localhost:4173

# Frontend
VITE_API_URL=http://localhost:8000

# Portoser
REGISTRY_FILE=/path/to/registry.yml
PORTOSER_CLI=/path/to/portoser

# Vault (optional)
VAULT_ADDR=http://127.0.0.1:8200

# Database (for MCP)
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=portoser
POSTGRES_USER=portoser
POSTGRES_PASSWORD=secret

# Redis (for WebSocket)
REDIS_HOST=localhost
REDIS_PORT=6379

# Authentication (optional)
JWT_SECRET=your-secret-key
KEYCLOAK_URL=https://keycloak.internal

Reverse Proxy (Caddy)

Add to Caddyfile:

portoser.internal {
    reverse_proxy localhost:8080

    # Optional: mTLS
    tls {
        client_auth {
            mode require_and_verify
            trusted_ca_cert_file /path/to/ca.crt
        }
    }
}

Troubleshooting

Can't Access Web UI

# Check if containers are running
docker-compose ps

# Check logs
docker-compose logs -f

# Verify ports
netstat -an | grep 8080

Real-Time Updates Not Working

# Check WebSocket connection
# In browser console:
# Look for WebSocket connection messages

# Check Redis
docker-compose logs redis

# Restart backend
docker-compose restart backend

Services Not Showing

# Check backend logs
docker-compose logs backend

# Verify registry path
docker-compose exec backend cat /app/registry.yml

# Test CLI
docker-compose exec backend ./portoser service list

Authentication Errors

# Check JWT secret
echo $JWT_SECRET

# Verify Keycloak config
curl $KEYCLOAK_URL/.well-known/openid-configuration

# Check logs
docker-compose logs backend | grep auth

API Documentation

The Web UI uses a REST API. Access API docs at:

Performance

Optimization Tips

  1. Enable Caching: Set appropriate cache headers
  2. Compress Assets: Enable gzip/brotli compression
  3. Lazy Loading: Load metrics/logs on demand
  4. Pagination: Limit results per page
  5. WebSocket: Use for real-time updates

Resource Usage

Typical resource requirements:

  • Memory: 256MB (backend) + 128MB (frontend)
  • CPU: < 1% idle, 5-10% under load
  • Disk: 50MB
  • Network: Minimal (WebSocket connection)

Security

Best Practices

  1. Use HTTPS: Always in production
  2. Enable Authentication: Don't expose publicly
  3. Use mTLS: For sensitive environments
  4. Regular Updates: Keep dependencies updated
  5. Audit Logs: Enable and monitor
  6. Rate Limiting: Prevent abuse

Next Steps