Server Dashboard

A customizable web dashboard for managing and monitoring multiple servers. Execute remote commands, monitor system status, and access services through a unified interface.

Features

• Remote Command Execution: Create buttons that execute SSH commands on your servers
• Status Monitoring: Real-time widgets for ZFS health, disk usage, Docker containers, and more
• Quick Links: Easy access to web services (Proxmox, Portainer, Grafana, etc.)
• Customizable: JSON-based configuration with web UI editor
• Docker-based: Easy deployment with Docker Compose

Quick Start

1. After cloning the project

cd HomeLabOverview

note: Make sure to replace the placeholder in the project with your IP address.

2. Build the project

make build

3. Run the project

make up

Access the dashboard at: http://localhost

3. Configure SSH Access

The dashboard needs SSH access to your servers. There are two methods:

Option A: Use Existing SSH Keys (Recommended)

Your ~/.ssh directory is already mounted in the container. Make sure your servers accept your SSH key:

# On your local machine, copy your SSH key to servers
ssh-copy-id user@your-server-ip

Option B: Use Password Authentication

Configure servers with password in data/config.json:

{
  "servers": [
    {
      "id": "server1",
      "name": "My Server",
      "host": "<IP_ADDRESS>",
      "port": 22,
      "username": "admin",
      "password": "your-password"
    }
  ]
}

Note: Password auth is less secure. SSH keys are recommended.

4. Create Your Configuration

Copy the example config:

cp data/config.example.json data/config.json

Edit data/config.json with your servers, or use the web UI (click "Edit Config").

Configuration Guide

Servers

Define your server connections:

{
  "servers": [
    {
      "id": "homelab",
      "name": "Home Lab Server",
      "host": "<IP_ADDRESS>",
      "port": 22,
      "username": "admin",
      "privateKeyPath": "/root/.ssh/id_rsa"
    }
  ]
}

Authentication Options:

• privateKeyPath: Path to SSH private key (inside container: /root/.ssh/id_rsa, /root/.ssh/id_ed25519, etc.)
• password: SSH password (if not using keys)
• If neither is specified, defaults to /root/.ssh/id_rsa

Command Buttons

Create buttons that run commands:

{
  "commandButtons": [
    {
      "id": "restart-docker",
      "label": "Restart Docker",
      "serverId": "homelab",
      "command": "sudo systemctl restart docker",
      "color": "bg-blue-600 hover:bg-blue-700"
    }
  ]
}

Status Widgets

Monitor server status:

{
  "statusWidgets": [
    {
      "id": "zfs-pool",
      "type": "zfs",
      "label": "ZFS Pool Status",
      "serverId": "homelab",
      "command": "zpool status",
      "refreshInterval": 30000
    },
    {
      "id": "disk-space",
      "type": "disk",
      "label": "Disk Usage",
      "serverId": "homelab",
      "command": "df -h",
      "refreshInterval": 60000
    }
  ]
}

Quick Links

Add links to services with icons:

{
  "quickLinks": [
    {
      "id": "proxmox",
      "label": "Proxmox",
      "url": "https://proxmox.local:8006",
      "icon": "server",
      "description": "VM Management"
    },
    {
      "id": "jellyfin",
      "label": "Jellyfin",
      "url": "http://<IP_ADDRESS>:8096",
      "icon": "video",
      "description": "Media Server"
    }
  ]
}

Available Icons:

• server - Server/VM management
• container - Docker/Container services
• database - Database services
• video - Media servers (Jellyfin, Emby)
• tv - Streaming (Plex, TV apps)
• film - Movie libraries
• music - Music services
• download - Download managers
• chart - Monitoring (Grafana, charts)
• settings - Configuration panels
• shield - Security services
• network - Network tools
• cloud - Cloud storage (Nextcloud)
• hard-drive - Storage management
• file - File managers
• book - Documentation/Wiki
• home - Home automation
• folder - File browsers
• box - Generic services
• globe - Web apps
• monitor - Monitoring dashboards

Make Commands

make build          # Build Docker images
make up             # Start containers
make down           # Stop containers
make restart        # Restart containers
make logs           # View all logs
make logs-backend   # View backend logs only
make logs-frontend  # View frontend logs only
make clean          # Remove containers and images

Troubleshooting

SSH Authentication Failed

1. Check SSH key permissions on your local machine:

   chmod 600 ~/.ssh/id_rsa
   chmod 700 ~/.ssh

2. Verify SSH access from your machine:

   ssh user@server-ip

3. Check container SSH access:

   docker exec -it server-dashboard-backend sh
   ls -la /root/.ssh/

4. Test SSH from container:

   docker exec -it server-dashboard-backend ssh user@server-ip

5. Check backend logs:

   make logs-backend

Container Won't Start

# Check logs
docker logs server-dashboard-backend
docker logs server-dashboard-frontend

# Rebuild
make clean
make build
make up

Port Already in Use

Edit docker-compose.yml to change ports:

frontend:
  ports:
    - "8080:80"  # Change 8080 to any available port

backend:
  ports:
    - "3002:3001"  # Change 3002 to any available port

Security Considerations

1. SSH Keys: Keep private keys secure. The container mounts ~/.ssh as read-only.
2. Network Access: Only expose ports on trusted networks.
3. HTTPS: Consider adding a reverse proxy with SSL for production use.
4. Passwords: Avoid storing passwords in config. Use SSH keys instead.
5. Sudo Commands: Be careful with commands requiring sudo. Ensure proper sudoers configuration on servers.

Development

Run in development mode with hot reload:

# Terminal 1
make backend-dev

# Terminal 2
make frontend-dev

Frontend: http://localhost:3000 Backend: http://localhost:3001

Architecture

• Frontend: React + TypeScript + Vite + Tailwind CSS
• Backend: Node.js + Express + TypeScript
• SSH: node-ssh library for remote command execution
• Deployment: Docker + Docker Compose

License

MIT

HomeLabOverview