Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

Add unified dev scripts and improve login UX

Juan Denis6bcbcab56a2f
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1ac64309..b19a7f4e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,113 +1,98 @@
# Contributing to ServerKit
-Thank you for your interest in contributing to ServerKit! This guide will help you get started.
+## Quick Setup
----
+### Windows (WSL2) — Recommended
+
+```powershell
+# 1. Install WSL (PowerShell as Admin)
+wsl --install -d Ubuntu-22.04
+# Restart, create user when prompted
+```
+
+```bash
+# 2. Run setup script
+cd /mnt/c/Users/YOUR_USERNAME/Documents/GitHub/ServerKit
+chmod +x ./scripts/dev/*.sh
+./scripts/dev/setup-wsl.sh
+
+# 3. Start dev servers
+./scripts/dev/start.sh
+```
+
+Open http://localhost:5173 — login: `admin` / `admin`
+
+> **Troubleshooting:** If you get `bad interpreter` error, fix line endings:
+> ```bash
+> sed -i 's/\r$//' ./scripts/dev/*.sh
+> ```
-## Table of Contents
+### Linux / macOS
-- [Code of Conduct](#code-of-conduct)
-- [Getting Started](#getting-started)
-- [Development Setup](#development-setup)
-- [Project Structure](#project-structure)
-- [Making Changes](#making-changes)
-- [Coding Standards](#coding-standards)
-- [Testing](#testing)
-- [Submitting Changes](#submitting-changes)
-- [Priority Areas](#priority-areas)
+```bash
+./scripts/dev/setup-linux.sh
+./scripts/dev/start.sh
+```
+
+### Docker
+
+```bash
+./scripts/dev/dev.bat up # Windows
+docker compose -f docker-compose.dev.yml up --build # Linux/Mac
+```
---
-## Code of Conduct
+## Quick Reference
-- Be respectful and inclusive
-- Provide constructive feedback
-- Focus on the issue, not the person
-- Help others learn and grow
+| Task | Command |
+|------|---------|
+| Start both | `./scripts/dev/start.sh` |
+| Backend only | `cd backend && source venv/bin/activate && python run.py` |
+| Frontend only | `cd frontend && npm run dev` |
+| Build frontend | `cd frontend && npm run build` |
---
-## Getting Started
+## Manual Setup
+
+<details>
+<summary>Click to expand manual setup steps</summary>
### Prerequisites
- Python 3.11+
- Node.js 20+
-- Docker (optional, for testing)
+- Docker (optional)
- Git
### Fork and Clone
```bash
-# Fork the repository on GitHub, then:
git clone https://github.com/YOUR_USERNAME/ServerKit.git
cd ServerKit
git remote add upstream https://github.com/jhd3197/ServerKit.git
```
----
-
-## Development Setup
-
### Backend Setup
```bash
-# Create virtual environment
cd backend
python -m venv venv
-
-# Activate virtual environment
-# Windows:
-venv\Scripts\activate
-# Linux/Mac:
-source venv/bin/activate
-
-# Install dependencies
+source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
-pip install -r requirements-dev.txt # Development dependencies
-
-# Copy environment file
-cp ../.env.example .env
-# Edit .env with your settings
-
-# Run development server
python run.py
```
-The backend will be available at `http://localhost:5000`.
-
### Frontend Setup
```bash
-# In a new terminal
cd frontend
-
-# Install dependencies
npm install
-
-# Run development server
npm run dev
```
-The frontend will be available at `http://localhost:5173` with hot-reload.
-
-### Running Both Together
-
-For development, run both the backend and frontend servers:
-
-```bash
-# Terminal 1 - Backend
-cd backend && python run.py
-
-# Terminal 2 - Frontend
-cd frontend && npm run dev
-```
-
-Or use Docker:
-
-```bash
-docker compose -f docker-compose.dev.yml up
-```
+</details>
---
diff --git a/GITEA_INTEGRATION_PLAN.md b/GITEA_INTEGRATION_PLAN.md
deleted file mode 100644
index bcb22ce4..00000000
--- a/GITEA_INTEGRATION_PLAN.md
+++ /dev/null
@@ -1,488 +0,0 @@
-# ServerKit Git Integration Plan
-
-## Overview
-
-This document outlines the plan to add integrated Git functionality to ServerKit:
-1. Add new "Git" sidebar page (similar to Firewall)
-2. Integrate Gitea as a first-class ServerKit feature
-3. Add GitHub/GitLab webhook support for repo sync
-4. Resource warnings before installation
-
----
-
-## Part 1: Architecture Notes
-
-### Current Gitea Template Status: Working
-
-The Gitea template works correctly. Key points:
-- **HTTP_PORT** (default 3000) → Auto-assigned and stored in Application.port
-- **SSH_PORT** (default 2222) → Auto-assigned and stored in `.serverkit-template.json`
-- Both ports are properly mapped in docker-compose.yml
-- App needs startup time (~30-60 seconds) for Gitea + PostgreSQL to initialize
-
-**Note:** Containers may take time to fully start. The UI should reflect "Starting..." status during initialization.
-
-### SSH Access for Git Operations
-
-SSH cannot be proxied via nginx (HTTP only). For Git SSH operations:
-- Users access SSH directly: `git clone ssh://git@server:2222/user/repo.git`
-- The SSH port is available in the app's `.serverkit-template.json` file
-- Consider displaying SSH port prominently in the UI
-
-### Potential Future Enhancement: Multi-Port Support
-
-For better UX with multi-port apps like Gitea, consider:
-- Adding `ssh_port` column to Application model
-- Displaying both HTTP and SSH ports in app details
-- This is optional - current system works fine
-
----
-
-## Part 2: New Git Sidebar Feature
-
-### Design: Git Page (Similar to Firewall Page)
-
-**Location in Sidebar:** Infrastructure section, after Docker
-
-**States:**
-1. **Not Installed** → Show installation button with resource warning
-2. **Installed but Not Configured** → Show setup wizard
-3. **Running** → Show Gitea dashboard with repos
-
-### UI Components
-
-**File: `frontend/src/pages/Git.jsx`**
-
-```jsx
-// Structure similar to Firewall.jsx
-
-const Git = () => {
- const [status, setStatus] = useState(null);
- const [loading, setLoading] = useState(true);
- const [showInstallModal, setShowInstallModal] = useState(false);
-
- // Tabs: Overview, Repositories, Settings, Webhooks
- const [activeTab, setActiveTab] = useState('overview');
-
- return (
- <div className="page git-page">
- {/* Not installed state */}
- {!status?.installed && (
- <div className="empty-state-large">
- <GitIcon />
- <h2>Git Server Not Installed</h2>
- <p>Install Gitea to manage your Git repositories</p>
-
- {/* Resource Warning */}
- <div className="resource-warning">
- <WarningIcon />
- <div>
- <strong>Resource Requirements</strong>
- <ul>
- <li>Memory: ~512MB minimum (1GB recommended)</li>
- <li>Storage: ~5GB for database + repositories</li>
- <li>Will also install PostgreSQL database</li>
- </ul>
- </div>
- </div>
-
- <button onClick={() => setShowInstallModal(true)}>
- Install Git Server
- </button>
- </div>
- )}
-
- {/* Installed state - show dashboard */}
- {status?.installed && (
- <>
- {/* Status cards, tabs, etc. */}
- </>
- )}
- </div>
- );
-};
-```
-
-### Backend API Endpoints
-
-**File: `backend/app/api/git.py`**
-
-```python
-from flask import Blueprint, jsonify, request
-from flask_jwt_extended import jwt_required
-from app.services.git_service import GitService
-
-git_bp = Blueprint('git', __name__, url_prefix='/api/git')
-
-@git_bp.route('/status', methods=['GET'])
-@jwt_required()
-def get_status():
- """Get Gitea installation status."""
- return jsonify(GitService.get_status())
-
-@git_bp.route('/install', methods=['POST'])
-@jwt_required()
-def install():
- """Install Gitea with PostgreSQL."""
- data = request.get_json() or {}
- return jsonify(GitService.install(
- admin_user=data.get('admin_user', 'admin'),
- admin_email=data.get('admin_email'),
- admin_password=data.get('admin_password')
- ))
-
-@git_bp.route('/uninstall', methods=['POST'])
-@jwt_required()
-def uninstall():
- """Uninstall Gitea and optionally remove data."""
- data = request.get_json() or {}
- return jsonify(GitService.uninstall(
- remove_data=data.get('remove_data', False)
- ))
-
-@git_bp.route('/repos', methods=['GET'])
-@jwt_required()
-def list_repos():
- """List all repositories."""
- return jsonify(GitService.list_repositories())
-
-@git_bp.route('/webhooks', methods=['GET'])
-@jwt_required()
-def list_webhooks():
- """List configured webhooks."""
- return jsonify(GitService.list_webhooks())
-
-@git_bp.route('/webhooks', methods=['POST'])
-@jwt_required()
-def create_webhook():
- """Create a webhook for GitHub/GitLab sync."""
- data = request.get_json()
- return jsonify(GitService.create_webhook(
- source=data.get('source'), # 'github', 'gitlab', 'bitbucket'
- repo_url=data.get('repo_url'),
- local_repo=data.get('local_repo'),
- secret=data.get('secret')
- ))
-```
-
-### Git Service
-
-**File: `backend/app/services/git_service.py`**
-
-```python
-"""Git/Gitea management service for ServerKit integrated Git."""
-
-import os
-import subprocess
-import secrets
-import requests
-from typing import Dict, List, Optional
-from app.services.template_service import TemplateService
-from app.services.docker_service import DockerService
-
-class GitService:
- """Service for managing integrated Gitea instance."""
-
- GITEA_APP_NAME = 'serverkit-gitea'
- GITEA_DATA_DIR = '/var/serverkit/gitea'
- GITEA_CONFIG_FILE = '/etc/serverkit/gitea.json'
-
- @classmethod
- def get_status(cls) -> Dict:
- """Check if Gitea is installed and running."""
- from app.models import Application
-
- app = Application.query.filter_by(name=cls.GITEA_APP_NAME).first()
-
- if not app:
- return {
- 'installed': False,
- 'running': False,
- 'http_port': None,
- 'ssh_port': None,
- 'url': None
- }
-
- # Check container status
- running = DockerService.is_container_running(cls.GITEA_APP_NAME)
-
- # Load config for ports
- config = cls._load_config()
-
- return {
- 'installed': True,
- 'running': running,
- 'http_port': app.port,
- 'ssh_port': app.ssh_port or config.get('ssh_port'),
- 'url': f"http://localhost:{app.port}",
- 'app_id': app.id,
- 'version': config.get('version', 'unknown')
- }
-
- @classmethod
- def install(cls, admin_user: str = 'admin',
- admin_email: str = None,
- admin_password: str = None) -> Dict:
- """Install Gitea as integrated ServerKit service."""
-
- # Check if already installed
- status = cls.get_status()
- if status['installed']:
- return {'success': False, 'error': 'Gitea is already installed'}
-
- # Generate secure password if not provided
- if not admin_password:
- admin_password = secrets.token_urlsafe(16)
-
- # Install using template service
- result = TemplateService.install_template(
- template_id='gitea',
- app_name=cls.GITEA_APP_NAME,
- user_variables={},
- user_id=1 # System user
- )
-
- if not result.get('success'):
- return result
-
- # Save config with admin credentials
- config = {
- 'admin_user': admin_user,
- 'admin_email': admin_email,
- 'admin_password': admin_password, # Should be encrypted
- 'http_port': result.get('variables', {}).get('HTTP_PORT'),
- 'ssh_port': result.get('variables', {}).get('SSH_PORT'),
- 'db_password': result.get('variables', {}).get('DB_PASSWORD'),
- 'installed_at': datetime.now().isoformat(),
- 'version': '1.21'
- }
- cls._save_config(config)
-
- # Update Application with SSH port
- from app.models import Application
- from app import db
-
- app = Application.query.filter_by(name=cls.GITEA_APP_NAME).first()
- if app:
- app.ssh_port = int(config['ssh_port'])
- db.session.commit()
-
- return {
- 'success': True,
- 'message': 'Gitea installed successfully',
- 'http_port': config['http_port'],
- 'ssh_port': config['ssh_port'],
- 'admin_user': admin_user,
- 'admin_password': admin_password, # Show once to user
- 'warning': 'Save these credentials - password shown only once!'
- }
-
- @classmethod
- def get_resource_requirements(cls) -> Dict:
- """Get resource requirements for Gitea installation."""
- return {
- 'memory_min': '512MB',
- 'memory_recommended': '1GB',
- 'storage_min': '5GB',
- 'storage_recommended': '20GB',
- 'components': [
- {'name': 'Gitea', 'memory': '~300MB', 'storage': '~100MB + repos'},
- {'name': 'PostgreSQL', 'memory': '~200MB', 'storage': '~1GB'}
- ],
- 'warning': 'Installation will spin up a PostgreSQL database container'
- }
-```
-
----
-
-## Part 3: GitHub Webhook Integration
-
-### Flow
-
-```
-[GitHub/GitLab] --webhook--> [ServerKit] --sync--> [Gitea/Local Repos]
-```
-
-### Webhook Endpoint
-
-**File: `backend/app/api/webhooks.py`**
-
-```python
-from flask import Blueprint, request, jsonify
-import hmac
-import hashlib
-
-webhooks_bp = Blueprint('webhooks', __name__, url_prefix='/api/webhooks')
-
-@webhooks_bp.route('/github/<repo_id>', methods=['POST'])
-def github_webhook(repo_id):
- """Handle GitHub webhook for repo sync."""
- # Verify signature
- signature = request.headers.get('X-Hub-Signature-256')
- if not verify_github_signature(request.data, signature, repo_id):
- return jsonify({'error': 'Invalid signature'}), 401
-
- event = request.headers.get('X-GitHub-Event')
- payload = request.get_json()
-
- if event == 'push':
- # Sync changes to local Gitea
- return handle_push_event(repo_id, payload)
- elif event == 'pull_request':
- return handle_pr_event(repo_id, payload)
-
- return jsonify({'status': 'ignored'})
-
-def verify_github_signature(payload: bytes, signature: str, repo_id: str) -> bool:
- """Verify GitHub webhook signature."""
- webhook_config = get_webhook_config(repo_id)
- if not webhook_config:
- return False
-
- secret = webhook_config['secret'].encode()
- expected = 'sha256=' + hmac.new(secret, payload, hashlib.sha256).hexdigest()
- return hmac.compare_digest(expected, signature)
-```
-
-### UI for Webhook Setup
-
-```
-+----------------------------------------------------+
-| Add GitHub Sync |
-+----------------------------------------------------+
-| |
-| GitHub Repository URL: |
-| [https://github.com/user/repo.git ] |
-| |
-| Local Repository (in Gitea): |
-| [Select or create new... v] |
-| |
-| Sync Direction: |
-| ( ) GitHub -> ServerKit (mirror) |
-| ( ) Bidirectional |
-| ( ) ServerKit -> GitHub (push) |
-| |
-| Webhook URL (copy this to GitHub): |
-| +----------------------------------------------+ |
-| | https://yourserver.com/api/webhooks/github/ | |
-| | abc123xyz | |
-| +----------------------------------------------+ |
-| [Copy] |
-| |
-| Webhook Secret: |
-| +----------------------------------------------+ |
-| | •••••••••••••••••• | |
-| +----------------------------------------------+ |
-| [Generate New] [Copy] |
-| |
-| [Cancel] [Create Webhook] |
-+----------------------------------------------------+
-```
-
----
-
-## Part 4: Implementation Order
-
-### Phase 1: Git Page Foundation (Priority: High)
-1. [ ] Add "Git" to sidebar in Sidebar.jsx
-2. [ ] Create Git.jsx page component
-3. [ ] Create _git.less styles
-4. [ ] Create git_service.py backend
-5. [ ] Create git.py API blueprint
-6. [ ] Register blueprint in __init__.py
-
-### Phase 2: Integrated Gitea (Priority: Medium)
-1. [ ] Create Gitea installation flow with resource warning
-2. [ ] Store Gitea config separately from regular apps
-3. [ ] Add Gitea-specific nginx config generation
-4. [ ] Add SSH port display in UI
-5. [ ] Create uninstall flow
-
-### Phase 3: Webhook Integration (Priority: Medium)
-1. [ ] Create webhook database model
-2. [ ] Create webhooks API endpoints
-3. [ ] Create webhook verification logic
-4. [ ] Create UI for webhook management
-5. [ ] Add GitHub webhook handler
-6. [ ] Add GitLab webhook handler (optional)
-
-### Phase 4: Polish (Priority: Low)
-1. [ ] Add repository browsing in Git page
-2. [ ] Add commit history viewer
-3. [ ] Add branch management
-4. [ ] Add user/team management integration
-
----
-
-## Part 5: File Structure
-
-```
-backend/
-├── app/
-│ ├── api/
-│ │ ├── git.py # NEW - Git API endpoints
-│ │ └── webhooks.py # NEW - Webhook handlers
-│ ├── models/
-│ │ └── webhook.py # NEW - Webhook model
-│ └── services/
-│ └── git_service.py # NEW - Git/Gitea service
-│
-frontend/
-├── src/
-│ ├── components/
-│ │ └── Sidebar.jsx # MODIFY - Add Git item
-│ ├── pages/
-│ │ └── Git.jsx # NEW - Git page
-│ ├── services/
-│ │ └── api.js # MODIFY - Add git endpoints
-│ └── styles/
-│ └── pages/
-│ └── _git.less # NEW - Git page styles
-```
-
----
-
-## Part 6: Database Changes
-
-```sql
--- New table: webhooks (for GitHub/GitLab sync)
-CREATE TABLE webhooks (
- id INTEGER PRIMARY KEY,
- name VARCHAR(100) NOT NULL,
- source VARCHAR(50) NOT NULL, -- 'github', 'gitlab', 'bitbucket'
- source_repo_url VARCHAR(500) NOT NULL,
- local_repo_id INTEGER,
- secret VARCHAR(100) NOT NULL,
- sync_direction VARCHAR(20) DEFAULT 'pull', -- 'pull', 'push', 'bidirectional'
- last_sync_at DATETIME,
- created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
- is_active BOOLEAN DEFAULT TRUE
-);
-
--- New table: git_config (for integrated Gitea settings)
-CREATE TABLE git_config (
- id INTEGER PRIMARY KEY,
- app_id INTEGER REFERENCES applications(id),
- admin_user VARCHAR(100),
- http_port INTEGER,
- ssh_port INTEGER,
- version VARCHAR(20),
- installed_at DATETIME,
- UNIQUE(app_id)
-);
-```
-
----
-
-## Summary
-
-| Feature | Status | Priority |
-|---------|--------|----------|
-| Git sidebar page | Need implementation | High |
-| Resource warning UI | Need implementation | High |
-| Integrated Gitea installation | Need implementation | High |
-| GitHub webhook sync | Need implementation | Medium |
-| GitLab webhook sync | Need implementation | Low |
-| Repository browser in UI | Need implementation | Low |
-
-This plan provides a roadmap for adding a fully integrated Git feature to ServerKit with resource warnings and webhook support for syncing with GitHub/GitLab repositories.
diff --git a/SERVERS_INTEGRATION_PLAN.md b/SERVERS_INTEGRATION_PLAN.md
deleted file mode 100644
index d090cf47..00000000
--- a/SERVERS_INTEGRATION_PLAN.md
+++ /dev/null
@@ -1,1535 +0,0 @@
-# ServerKit Multi-Server Management Integration Plan
-## "ServerKit Agents" - THE Comprehensive Server Management Solution
-
-> **Vision**: Transform ServerKit from a single-server management tool into a distributed server orchestration platform that manages unlimited servers from a single dashboard.
-
----
-
-## Table of Contents
-1. [Executive Summary](#executive-summary)
-2. [Architecture Overview](#architecture-overview)
-3. [Security Model (Critical!)](#security-model)
-4. [Agent Design](#agent-design)
-5. [Database Schema](#database-schema)
-6. [API Design](#api-design)
-7. [Frontend Design](#frontend-design)
-8. [Installation & Packaging](#installation--packaging)
-9. [Communication Protocol](#communication-protocol)
-10. [Feature Breakdown](#feature-breakdown)
-11. [Phase Implementation Plan](#phase-implementation-plan)
-12. [Risk Assessment](#risk-assessment)
-
----
-
-## 1. Executive Summary
-
-### What We're Building
-A lightweight agent system that allows ServerKit to manage multiple remote servers (Windows/Linux) from a single dashboard. Users install a small agent on their servers, connect it to their ServerKit instance, and gain full Docker management, monitoring, and remote execution capabilities.
-
-### Why Security is ABSOLUTELY Required
-Even though we're "just managing Docker," this is a critical security concern:
-
-| Risk | Impact | Why It Matters |
-|------|--------|----------------|
-| **Docker = Root Access** | Critical | Docker can mount host filesystem, access kernel, run privileged containers |
-| **Remote Code Execution** | Critical | Agents execute commands on remote servers |
-| **Network Exposure** | High | Agents may be on internal networks with sensitive data |
-| **Credential Theft** | High | Stolen agent keys = full server access |
-| **Man-in-the-Middle** | High | Unencrypted traffic can be intercepted and modified |
-| **Supply Chain** | Medium | Malicious agents could be installed |
-
-**Bottom Line**: We need enterprise-grade security from day one. This isn't optional.
-
----
-
-## 2. Architecture Overview
-
-### High-Level Architecture
-
-```
-┌─────────────────────────────────────────────────────────────────────────────────┐
-│ ServerKit Control Plane │
-│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
-│ │ Web UI │ │ REST API │ │ SocketIO │ │ Agent Gateway │ │
-│ │ (React) │ │ (Flask) │ │ Server │ │ (WebSocket Handler) │ │
-│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └───────────┬─────────────┘ │
-│ │ │ │ │ │
-│ └────────────────┴────────────────┴─────────────────────┤ │
-│ │ │
-│ ┌──────────────────────────────────────────────────────────────┴─────────────┐ │
-│ │ Agent Registry Service │ │
-│ │ - Agent authentication - Health tracking - Command routing │ │
-│ │ - Connection management - Load balancing - Failover handling │ │
-│ └──────────────────────────────────────────────────────────────┬─────────────┘ │
-│ │ │
-│ ┌──────────────────────────────────────────────────────────────┴─────────────┐ │
-│ │ PostgreSQL Database │ │
-│ │ Servers, Agents, Commands, Metrics, Audit Logs, etc. │ │
-│ └────────────────────────────────────────────────────────────────────────────┘ │
-└─────────────────────────────────────────────────────────────────────────────────┘
- │
- ┌─────────────────┼─────────────────┐
- │ │ │
- ┌────────┴────────┐ ┌──────┴──────┐ ┌────────┴────────┐
- │ WSS/TLS │ │ WSS/TLS │ │ WSS/TLS │
- │ Connection │ │ Connection │ │ Connection │
- └────────┬────────┘ └──────┬──────┘ └────────┬────────┘
- │ │ │
- ┌───────────────┴───────┐ ┌──────┴──────┐ ┌───────┴───────────────┐
- │ Linux Server │ │ Windows PC │ │ Linux Server │
- │ ┌─────────────────┐ │ │ ┌─────────┐ │ │ ┌─────────────────┐ │
- │ │ ServerKit Agent │ │ │ │ Agent │ │ │ │ ServerKit Agent │ │
- │ │ (Go binary) │ │ │ │ (Go) │ │ │ │ (Go binary) │ │
- │ └────────┬────────┘ │ │ └────┬────┘ │ │ └────────┬────────┘ │
- │ │ │ │ │ │ │ │ │
- │ ┌────────┴────────┐ │ │ ┌────┴────┐ │ │ ┌────────┴────────┐ │
- │ │ Docker │ │ │ │ Docker │ │ │ │ Docker │ │
- │ │ Engine │ │ │ │ Desktop │ │ │ │ Engine │ │
- │ └─────────────────┘ │ │ └─────────┘ │ │ └─────────────────┘ │
- └───────────────────────┘ └─────────────┘ └───────────────────────┘
-```
-
-### Component Responsibilities
-
-| Component | Responsibility |
-|-----------|---------------|
-| **Control Plane** | Central management, UI, API, database |
-| **Agent Gateway** | WebSocket server for agent connections |
-| **Agent Registry** | Track connected agents, route commands |
-| **ServerKit Agent** | Lightweight daemon on remote servers |
-| **Local Executor** | Execute Docker/system commands locally |
-
----
-
-## 3. Security Model
-
-### 3.1 Authentication Layers
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│ SECURITY ARCHITECTURE │
-├─────────────────────────────────────────────────────────────────┤
-│ │
-│ Layer 1: Transport Security (TLS 1.3) │
-│ ┌─────────────────────────────────────────────────────────────┐│
-│ │ - All communication over WSS (WebSocket Secure) ││
-│ │ - Certificate validation (reject self-signed in prod) ││
-│ │ - Perfect forward secrecy ││
-│ └─────────────────────────────────────────────────────────────┘│
-│ │
-│ Layer 2: Agent Authentication │
-│ ┌─────────────────────────────────────────────────────────────┐│
-│ │ - API Key + Secret pair (generated on registration) ││
-│ │ - HMAC-SHA256 signed handshake ││
-│ │ - Short-lived session tokens (1 hour, auto-refresh) ││
-│ │ - Optional: mTLS for enterprise deployments ││
-│ └─────────────────────────────────────────────────────────────┘│
-│ │
-│ Layer 3: Command Authorization │
-│ ┌─────────────────────────────────────────────────────────────┐│
-│ │ - Per-server permission scopes ││
-│ │ - Command whitelist (allowed operations) ││
-│ │ - Request signing with timestamp (prevent replay) ││
-│ │ - Audit logging of all operations ││
-│ └─────────────────────────────────────────────────────────────┘│
-│ │
-│ Layer 4: Data Protection │
-│ ┌─────────────────────────────────────────────────────────────┐│
-│ │ - Secrets encrypted at rest (agent keys, tokens) ││
-│ │ - No plaintext credentials in transit ││
-│ │ - Secure secret injection to containers ││
-│ └─────────────────────────────────────────────────────────────┘│
-│ │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-### 3.2 Agent Registration Flow
-
-```
-┌──────────┐ ┌──────────────┐ ┌──────────┐
-│ User │ │ Control Plane │ │ Agent │
-└────┬─────┘ └───────┬──────┘ └────┬─────┘
- │ │ │
- │ 1. Create Server (UI) │ │
- │ ─────────────────────────────────> │
- │ │ │
- │ 2. Returns registration token │ │
- │ <───────────────────────────────── │
- │ (24-hour expiry, single-use) │ │
- │ │ │
- │ 3. Install agent with token │ │
- │ ─────────────────────────────────────────────────────────────────>
- │ │ │
- │ │ 4. Agent connects with token │
- │ │ <──────────────────────────────
- │ │ │
- │ │ 5. Validates token, generates │
- │ │ permanent API key pair │
- │ │ ──────────────────────────────>
- │ │ │
- │ │ 6. Agent stores keys securely │
- │ │ (encrypted on disk) │
- │ │ │
- │ 7. Server shows as "Connected" │ │
- │ <───────────────────────────────── │
- │ │ │
-```
-
-### 3.3 Permission Scopes
-
-```python
-# Granular permissions per server
-AGENT_SCOPES = {
- # Docker Operations
- 'docker:containers:read', # List, inspect containers
- 'docker:containers:write', # Create, start, stop, remove
- 'docker:containers:exec', # Exec into containers (high risk!)
- 'docker:images:read', # List, inspect images
- 'docker:images:write', # Pull, build, remove images
- 'docker:compose:read', # List compose stacks
- 'docker:compose:write', # Deploy/remove compose stacks
- 'docker:volumes:read',
- 'docker:volumes:write',
- 'docker:networks:read',
- 'docker:networks:write',
-
- # System Operations
- 'system:metrics:read', # CPU, memory, disk metrics
- 'system:processes:read', # Process list
- 'system:logs:read', # Read log files
- 'system:exec', # Execute arbitrary commands (DANGEROUS!)
-
- # File Operations
- 'files:read', # Read files on server
- 'files:write', # Write files (limited paths)
-
- # Agent Management
- 'agent:update', # Self-update agent
- 'agent:restart', # Restart agent service
-}
-
-# Preset permission profiles
-PERMISSION_PROFILES = {
- 'docker_readonly': [
- 'docker:containers:read',
- 'docker:images:read',
- 'docker:compose:read',
- 'system:metrics:read',
- ],
- 'docker_manager': [
- 'docker:*',
- 'system:metrics:read',
- 'system:logs:read',
- ],
- 'full_access': ['*'], # All permissions (admin only)
-}
-```
-
-### 3.4 Security Features Checklist
-
-- [ ] **TLS everywhere**: WSS for agent connections, HTTPS for API
-- [ ] **API key rotation**: Manual and automatic key rotation
-- [ ] **IP allowlisting**: Optional restriction of agent IPs
-- [ ] **Rate limiting**: Per-agent command rate limits
-- [ ] **Audit logging**: Every command logged with user, timestamp, result
-- [ ] **Anomaly detection**: Alert on unusual patterns (many failed commands, etc.)
-- [ ] **Secrets management**: Encrypted storage, never logged
-- [ ] **Session management**: Revoke agent sessions instantly
-- [ ] **Command signing**: HMAC-signed commands with timestamp
-- [ ] **Replay protection**: Nonce + timestamp validation
-
----
-
-## 4. Agent Design
-
-### 4.1 Technology Choice: Go
-
-**Why Go?**
-| Reason | Benefit |
-|--------|---------|
-| Single binary | No runtime dependencies, easy distribution |
-| Cross-platform | Compile for Windows, Linux, macOS, ARM |
-| Low memory | ~10-20MB RAM typical usage |
-| Fast startup | Instant service startup |
-| Excellent networking | Built-in WebSocket, HTTP, TLS support |
-| Docker SDK | Official Docker Go SDK available |
-
-### 4.2 Agent Architecture
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│ ServerKit Agent │
-├─────────────────────────────────────────────────────────────────┤
-│ │
-│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
-│ │ Connection │ │ Command │ │ Metrics │ │
-│ │ Manager │ │ Executor │ │ Collector │ │
-│ │ │ │ │ │ │ │
-│ │ - WebSocket │ │ - Docker API │ │ - CPU/RAM/Disk │ │
-│ │ - Auto-reconnect│ │ - System exec │ │ - Network I/O │ │
-│ │ - Heartbeat │ │ - File ops │ │ - Docker stats │ │
-│ │ - TLS handling │ │ - Sandboxing │ │ - Custom metrics│ │
-│ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ │
-│ │ │ │ │
-│ ┌────────┴────────────────────┴────────────────────┴────────┐ │
-│ │ Core Event Loop │ │
-│ │ - Message queue - Command validation │ │
-│ │ - Priority handling - Response serialization │ │
-│ └────────────────────────────┬──────────────────────────────┘ │
-│ │ │
-│ ┌────────────────────────────┴──────────────────────────────┐ │
-│ │ Security Module │ │
-│ │ - Key storage (encrypted) - Request validation │ │
-│ │ - HMAC signing - Permission checking │ │
-│ └───────────────────────────────────────────────────────────┘ │
-│ │
-│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
-│ │ Config Store │ │ Local Cache │ │ Update Manager │ │
-│ │ (encrypted) │ │ (metrics/logs) │ │ (self-update) │ │
-│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
-│ │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-### 4.3 Agent Features
-
-#### Core Features
-- **Persistent WebSocket connection** with auto-reconnect
-- **Heartbeat** every 30 seconds (configurable)
-- **Graceful shutdown** on SIGTERM/SIGINT
-- **Local metric buffering** when disconnected
-- **Self-update** capability (secure, signed updates)
-
-#### Docker Integration
-- Full Docker Engine API access
-- Container lifecycle management
-- Image management (pull, build, tag, push)
-- Docker Compose stack deployment
-- Volume and network management
-- Container logs streaming
-- Container stats streaming
-- Registry authentication
-
-#### System Integration
-- CPU, memory, disk metrics via cross-platform libraries
-- Process listing
-- Network interface stats
-- Service status (systemd/Windows services)
-- Log file streaming
-
-### 4.4 Agent Configuration
-
-```yaml
-# /etc/serverkit-agent/config.yaml (Linux)
-# C:\ProgramData\ServerKit\Agent\config.yaml (Windows)
-
-server:
- url: wss://your-serverkit.example.com/agent/ws
- # Alternative: ws://localhost:5000/agent/ws (dev only!)
-
-agent:
- id: "auto-generated-uuid"
- name: "production-server-1" # Human-friendly name
-
-auth:
- key_file: /etc/serverkit-agent/agent.key # Encrypted
- # Key is generated during registration
-
-features:
- docker: true
- metrics: true
- metrics_interval: 10s
- logs: true
- file_access: false # Disabled by default
- exec: false # Disabled by default (dangerous)
-
-docker:
- socket: /var/run/docker.sock # Linux
- # socket: npipe:////./pipe/docker_engine # Windows
-
-security:
- allowed_paths: [] # For file operations
- blocked_commands: [] # Regex patterns to block
- max_exec_timeout: 300s
-
-logging:
- level: info
- file: /var/log/serverkit-agent/agent.log
- max_size: 100MB
- max_backups: 5
-```
-
-### 4.5 Resource Usage Targets
-
-| Resource | Target | Maximum |
-|----------|--------|---------|
-| Memory | 15 MB | 50 MB |
-| CPU (idle) | <0.1% | 1% |
-| CPU (active) | <2% | 10% |
-| Disk | 20 MB | 50 MB |
-| Network (idle) | <1 KB/s | 10 KB/s |
-
----
-
-## 5. Database Schema
-
-### 5.1 New Models
-
-```python
-# backend/app/models/server.py
-
-class Server(db.Model):
- """Represents a remote server managed by ServerKit"""
- __tablename__ = 'servers'
-
- id = db.Column(db.String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
-
- # Basic Info
- name = db.Column(db.String(100), nullable=False)
- description = db.Column(db.Text)
- hostname = db.Column(db.String(255)) # Reported by agent
- ip_address = db.Column(db.String(45)) # IPv4 or IPv6
-
- # Organization
- group_id = db.Column(db.String(36), db.ForeignKey('server_groups.id'), nullable=True)
- tags = db.Column(db.JSON, default=list) # ["production", "us-east", "docker"]
-
- # Status
- status = db.Column(db.String(20), default='pending')
- # pending, connecting, online, offline, error, maintenance
- last_seen = db.Column(db.DateTime)
- last_error = db.Column(db.Text)
-
- # Agent Info
- agent_version = db.Column(db.String(20))
- agent_id = db.Column(db.String(36), unique=True) # Agent's UUID
-
- # System Info (reported by agent)
- os_type = db.Column(db.String(20)) # linux, windows, darwin
- os_version = db.Column(db.String(100))
- architecture = db.Column(db.String(20)) # amd64, arm64
- cpu_cores = db.Column(db.Integer)
- total_memory = db.Column(db.BigInteger) # bytes
- total_disk = db.Column(db.BigInteger) # bytes
- docker_version = db.Column(db.String(50))
-
- # Security
- api_key_hash = db.Column(db.String(256)) # bcrypt hash
- api_key_prefix = db.Column(db.String(8)) # For identification: "sk_abc123"
- permissions = db.Column(db.JSON, default=list) # List of scopes
- allowed_ips = db.Column(db.JSON, default=list) # IP whitelist (empty = all)
-
- # Registration
- registration_token_hash = db.Column(db.String(256))
- registration_token_expires = db.Column(db.DateTime)
- registered_at = db.Column(db.DateTime)
- registered_by = db.Column(db.Integer, db.ForeignKey('users.id'))
-
- # Timestamps
- created_at = db.Column(db.DateTime, default=datetime.utcnow)
- updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
-
- # Relationships
- group = db.relationship('ServerGroup', back_populates='servers')
- metrics = db.relationship('ServerMetrics', back_populates='server', lazy='dynamic')
- commands = db.relationship('ServerCommand', back_populates='server', lazy='dynamic')
- containers = db.relationship('ServerContainer', back_populates='server', lazy='dynamic')
-
-
-class ServerGroup(db.Model):
- """Group servers for organization"""
- __tablename__ = 'server_groups'
-
- id = db.Column(db.String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
- name = db.Column(db.String(100), nullable=False)
- description = db.Column(db.Text)
- color = db.Column(db.String(7)) # Hex color for UI
- icon = db.Column(db.String(50)) # Icon name
- parent_id = db.Column(db.String(36), db.ForeignKey('server_groups.id')) # Nested groups
-
- created_at = db.Column(db.DateTime, default=datetime.utcnow)
-
- # Relationships
- servers = db.relationship('Server', back_populates='group')
- children = db.relationship('ServerGroup', backref=db.backref('parent', remote_side=[id]))
-
-
-class ServerMetrics(db.Model):
- """Historical metrics from servers"""
- __tablename__ = 'server_metrics'
-
- id = db.Column(db.BigInteger, primary_key=True, autoincrement=True)
- server_id = db.Column(db.String(36), db.ForeignKey('servers.id'), nullable=False)
-
- timestamp = db.Column(db.DateTime, default=datetime.utcnow, index=True)
-
- # System Metrics
- cpu_percent = db.Column(db.Float)
- memory_percent = db.Column(db.Float)
- memory_used = db.Column(db.BigInteger)
- disk_percent = db.Column(db.Float)
- disk_used = db.Column(db.BigInteger)
- network_rx = db.Column(db.BigInteger) # Bytes received
- network_tx = db.Column(db.BigInteger) # Bytes transmitted
-
- # Docker Metrics
- container_count = db.Column(db.Integer)
- container_running = db.Column(db.Integer)
- image_count = db.Column(db.Integer)
-
- # Additional data as JSON
- extra = db.Column(db.JSON)
-
- server = db.relationship('Server', back_populates='metrics')
-
- __table_args__ = (
- db.Index('ix_server_metrics_server_time', 'server_id', 'timestamp'),
- )
-
-
-class ServerCommand(db.Model):
- """Audit log of commands executed on servers"""
- __tablename__ = 'server_commands'
-
- id = db.Column(db.String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
- server_id = db.Column(db.String(36), db.ForeignKey('servers.id'), nullable=False)
- user_id = db.Column(db.Integer, db.ForeignKey('users.id'))
-
- # Command details
- command_type = db.Column(db.String(50)) # docker:container:start, system:exec, etc.
- command_data = db.Column(db.JSON) # The actual command/parameters
-
- # Execution
- status = db.Column(db.String(20)) # pending, running, completed, failed, timeout
- started_at = db.Column(db.DateTime)
- completed_at = db.Column(db.DateTime)
-
- # Result
- result = db.Column(db.JSON)
- error = db.Column(db.Text)
- exit_code = db.Column(db.Integer)
-
- created_at = db.Column(db.DateTime, default=datetime.utcnow)
-
- server = db.relationship('Server', back_populates='commands')
- user = db.relationship('User')
-
-
-class ServerContainer(db.Model):
- """Cached container state from remote servers"""
- __tablename__ = 'server_containers'
-
- id = db.Column(db.String(36), primary_key=True) # Docker container ID
- server_id = db.Column(db.String(36), db.ForeignKey('servers.id'), nullable=False)
-
- name = db.Column(db.String(255))
- image = db.Column(db.String(255))
- status = db.Column(db.String(50))
- state = db.Column(db.String(20)) # running, paused, exited, etc.
-
- created = db.Column(db.DateTime)
- started_at = db.Column(db.DateTime)
-
- ports = db.Column(db.JSON)
- labels = db.Column(db.JSON)
-
- # Stats snapshot
- cpu_percent = db.Column(db.Float)
- memory_usage = db.Column(db.BigInteger)
- memory_limit = db.Column(db.BigInteger)
-
- last_updated = db.Column(db.DateTime, default=datetime.utcnow)
-
- server = db.relationship('Server', back_populates='containers')
-
-
-class AgentSession(db.Model):
- """Active agent WebSocket sessions"""
- __tablename__ = 'agent_sessions'
-
- id = db.Column(db.String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
- server_id = db.Column(db.String(36), db.ForeignKey('servers.id'), nullable=False)
-
- session_token_hash = db.Column(db.String(256))
- connected_at = db.Column(db.DateTime, default=datetime.utcnow)
- last_heartbeat = db.Column(db.DateTime, default=datetime.utcnow)
-
- ip_address = db.Column(db.String(45))
- user_agent = db.Column(db.String(255)) # Agent version info
-
- is_active = db.Column(db.Boolean, default=True)
- disconnected_at = db.Column(db.DateTime)
- disconnect_reason = db.Column(db.String(100))
-```
-
-### 5.2 Schema Diagram
-
-```
-┌─────────────────────┐ ┌─────────────────────┐
-│ server_groups │ │ users │
-├─────────────────────┤ ├─────────────────────┤
-│ id (PK) │ │ id (PK) │
-│ name │ │ ... │
-│ description │ └──────────┬──────────┘
-│ color │ │
-│ parent_id (FK)──────┼──┐ │
-└──────────┬──────────┘ │ │
- │ │ │
- │ 1:N │ │
- │ │ │
-┌──────────┴──────────┐ │ │
-│ servers │◄─┘ │
-├─────────────────────┤ │
-│ id (PK) │ │
-│ name │ │
-│ group_id (FK)───────┼─────────────────┘
-│ registered_by (FK)──┼─────────────────┘
-│ status │
-│ agent_id │
-│ os_type │
-│ ... │
-└──────────┬──────────┘
- │
- ┌─────┼─────┬───────────┐
- │ │ │ │
- │ 1:N │ 1:N │ 1:N │ 1:N
- │ │ │ │
- ▼ ▼ ▼ ▼
-┌─────────┐ ┌─────────┐ ┌──────────┐ ┌──────────────┐
-│ metrics │ │commands │ │containers│ │agent_sessions│
-└─────────┘ └─────────┘ └──────────┘ └──────────────┘
-```
-
----
-
-## 6. API Design
-
-### 6.1 Server Management Endpoints
-
-```
-# Server CRUD
-GET /api/v1/servers # List all servers
-POST /api/v1/servers # Create new server (generates reg token)
-GET /api/v1/servers/:id # Get server details
-PUT /api/v1/servers/:id # Update server (name, group, etc.)
-DELETE /api/v1/servers/:id # Remove server
-
-# Server Status
-GET /api/v1/servers/:id/status # Get current status & metrics
-POST /api/v1/servers/:id/ping # Force ping/health check
-
-# Registration
-POST /api/v1/servers/:id/regenerate-token # Generate new registration token
-POST /api/v1/servers/:id/rotate-key # Rotate API key
-
-# Permissions
-GET /api/v1/servers/:id/permissions # Get current permissions
-PUT /api/v1/servers/:id/permissions # Update permissions
-
-# Groups
-GET /api/v1/server-groups # List groups
-POST /api/v1/server-groups # Create group
-PUT /api/v1/server-groups/:id # Update group
-DELETE /api/v1/server-groups/:id # Delete group
-```
-
-### 6.2 Remote Docker Endpoints
-
-```
-# Containers
-GET /api/v1/servers/:id/docker/containers # List containers
-GET /api/v1/servers/:id/docker/containers/:cid # Inspect container
-POST /api/v1/servers/:id/docker/containers # Create container
-POST /api/v1/servers/:id/docker/containers/:cid/start
-POST /api/v1/servers/:id/docker/containers/:cid/stop
-POST /api/v1/servers/:id/docker/containers/:cid/restart
-DELETE /api/v1/servers/:id/docker/containers/:cid # Remove container
-GET /api/v1/servers/:id/docker/containers/:cid/logs # Get logs
-GET /api/v1/servers/:id/docker/containers/:cid/stats # Get stats
-
-# Images
-GET /api/v1/servers/:id/docker/images # List images
-POST /api/v1/servers/:id/docker/images/pull # Pull image
-DELETE /api/v1/servers/:id/docker/images/:iid # Remove image
-
-# Compose
-GET /api/v1/servers/:id/docker/compose # List stacks
-POST /api/v1/servers/:id/docker/compose # Deploy stack
-DELETE /api/v1/servers/:id/docker/compose/:name # Remove stack
-
-# Volumes & Networks
-GET /api/v1/servers/:id/docker/volumes
-GET /api/v1/servers/:id/docker/networks
-```
-
-### 6.3 Metrics & Monitoring
-
-```
-# Real-time metrics (via WebSocket)
-WS /api/v1/servers/:id/metrics/stream
-
-# Historical metrics
-GET /api/v1/servers/:id/metrics?from=&to=&interval=
-
-# Cross-server comparison
-GET /api/v1/servers/metrics/compare?ids=1,2,3&metric=cpu
-
-# Aggregated dashboard
-GET /api/v1/servers/overview # All servers health summary
-```
-
-### 6.4 Agent Gateway WebSocket Protocol
-
-```
-# Agent connects to: wss://serverkit.example.com/agent/ws
-
-# Handshake
-→ { "type": "auth", "agent_id": "...", "signature": "hmac(...)", "timestamp": ... }
-← { "type": "auth_ok", "session_token": "...", "expires": ... }
-
-# Heartbeat
-→ { "type": "heartbeat", "metrics": {...} }
-← { "type": "heartbeat_ack" }
-
-# Command from server
-← { "type": "command", "id": "uuid", "action": "docker:container:start", "params": {...} }
-→ { "type": "command_result", "id": "uuid", "success": true, "data": {...} }
-
-# Streaming (logs, stats)
-← { "type": "subscribe", "channel": "container:abc123:logs" }
-→ { "type": "stream", "channel": "...", "data": "log line..." }
-← { "type": "unsubscribe", "channel": "..." }
-
-# Error
-→ { "type": "error", "code": "...", "message": "..." }
-```
-
----
-
-## 7. Frontend Design
-
-### 7.1 Navigation Structure
-
-```
-Sidebar (Updated)
-├── Dashboard
-├── Applications
-├── ─────────────
-├── Servers (NEW!) ← New section
-│ ├── Overview ← Multi-server dashboard
-│ ├── All Servers ← List/grid view
-│ └── Groups ← Server groups management
-├── ─────────────
-├── Docker ← Now shows server selector
-├── Databases
-├── Domains
-├── ...
-```
-
-### 7.2 Key Pages
-
-#### Servers Overview (`/servers`)
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│ Servers Overview [+ Add Server] │
-├─────────────────────────────────────────────────────────────────────────────┤
-│ │
-│ ┌─────────────────────────────────────────────────────────────────────────┐│
-│ │ Summary Cards ││
-│ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ ││
-│ │ │ Total │ │ Online │ │ Offline │ │ Containers│ │ Avg CPU │ ││
-│ │ │ 12 │ │ 10 │ │ 2 │ │ 47 │ │ 34% │ ││
-│ │ └───────────┘ └───────────┘ └───────────┘ └───────────┘ └───────────┘ ││
-│ └─────────────────────────────────────────────────────────────────────────┘│
-│ │
-│ ┌─────────────────────────────────────────────────────────────────────────┐│
-│ │ Server Health Grid ││
-│ │ ││
-│ │ Production (4 servers) ││
-│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ││
-│ │ │ 🟢 web-1 │ │ 🟢 web-2 │ │ 🟢 db-1 │ │ 🔴 cache │ ││
-│ │ │ CPU: 45% │ │ CPU: 32% │ │ CPU: 12% │ │ OFFLINE │ ││
-│ │ │ RAM: 67% │ │ RAM: 58% │ │ RAM: 89% │ │ │ ││
-│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ ││
-│ │ ││
-│ │ Development (3 servers) ││
-│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ││
-│ │ │ 🟢 dev-1 │ │ 🟡 dev-2 │ │ 🟢 test │ ││
-│ │ │ CPU: 23% │ │ CPU: 78% │ │ CPU: 5% │ ││
-│ │ └──────────┘ └──────────┘ └──────────┘ ││
-│ └─────────────────────────────────────────────────────────────────────────┘│
-│ │
-│ ┌─────────────────────────────────────────────────────────────────────────┐│
-│ │ Cross-Server Metrics Comparison [CPU▼] [24h▼] ││
-│ │ ││
-│ │ 100% ┤ ││
-│ │ │ ╭─╮ ││
-│ │ 75% ┤ ╱ ╲ ╭───╮ ── web-1 ││
-│ │ │ ╱ ╲ ╱ ╲ ── web-2 ││
-│ │ 50% ┤─╱──────╲╱───────╲─────── ── db-1 ││
-│ │ │ ││
-│ │ 25% ┤ ││
-│ │ └──────────────────────────────────────────────────────────── ││
-│ └─────────────────────────────────────────────────────────────────────────┘│
-└─────────────────────────────────────────────────────────────────────────────┘
-```
-
-#### Add Server Flow (`/servers/add`)
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│ Add New Server │
-├─────────────────────────────────────────────────────────────────────────────┤
-│ │
-│ Step 1: Server Details │
-│ ───────────────────────────────────────────────────────────────────────── │
-│ │
-│ Server Name: [production-server-1 ] │
-│ Description: [Main production server ] │
-│ Group: [Production ▼] │
-│ Tags: [production] [us-east] [+] │
-│ │
-│ ───────────────────────────────────────────────────────────────────────── │
-│ │
-│ Step 2: Permissions │
-│ ───────────────────────────────────────────────────────────────────────── │
-│ │
-│ Permission Profile: [Docker Manager (Recommended) ▼] │
-│ │
-│ ☑ Docker: Containers (read/write) │
-│ ☑ Docker: Images (read/write) │
-│ ☑ Docker: Compose (read/write) │
-│ ☑ System: Metrics (read) │
-│ ☑ System: Logs (read) │
-│ ☐ System: Execute commands (⚠️ High risk) │
-│ ☐ Files: Read/Write (⚠️ High risk) │
-│ │
-│ [Cancel] [Create Server]│
-└─────────────────────────────────────────────────────────────────────────────┘
-
-# After creation:
-┌─────────────────────────────────────────────────────────────────────────────┐
-│ Install Agent │
-├─────────────────────────────────────────────────────────────────────────────┤
-│ │
-│ Your server has been created! Install the agent using one of these methods:│
-│ │
-│ ┌─────────────────────────────────────────────────────────────────────────┐│
-│ │ Linux (One-liner) [Copy] ││
-│ │ ││
-│ │ curl -fsSL https://serverkit.example.com/install.sh | sudo bash -s -- \ ││
-│ │ --token "sk_reg_abc123xyz..." ││
-│ └─────────────────────────────────────────────────────────────────────────┘│
-│ │
-│ ┌─────────────────────────────────────────────────────────────────────────┐│
-│ │ Windows (PowerShell - Run as Administrator) [Copy] ││
-│ │ ││
-│ │ irm https://serverkit.example.com/install.ps1 | iex; ` ││
-│ │ Install-ServerKitAgent -Token "sk_reg_abc123xyz..." ││
-│ └─────────────────────────────────────────────────────────────────────────┘│
-│ │
-│ ┌─────────────────────────────────────────────────────────────────────────┐│
-│ │ Manual Download ││
-│ │ ││
-│ │ [Download Linux x64] [Download Linux ARM64] ││
-│ │ [Download Windows] [Download macOS] ││
-│ │ ││
-│ │ Registration Token: sk_reg_abc123xyz... (expires in 24 hours) [Copy] ││
-│ └─────────────────────────────────────────────────────────────────────────┘│
-│ │
-│ Waiting for agent to connect... ⏳ │
-│ │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
-
-#### Server Detail Page (`/servers/:id`)
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│ ← Back production-server-1 🟢 Online [Actions ▼] [Settings]│
-├─────────────────────────────────────────────────────────────────────────────┤
-│ │
-│ [Overview] [Containers] [Images] [Compose] [Metrics] [Logs] [Terminal] │
-│ │
-│ ┌─────────────────────────────────────────────────────────────────────────┐│
-│ │ System Information ││
-│ │ ─────────────────────────────────────────────────────────────────────── ││
-│ │ OS: Ubuntu 22.04 LTS Docker: 24.0.5 ││
-│ │ Arch: x86_64 Agent: 1.0.0 ││
-│ │ CPUs: 8 cores Uptime: 45 days ││
-│ │ Memory: 32 GB IP: 10.0.1.50 ││
-│ └─────────────────────────────────────────────────────────────────────────┘│
-│ │
-│ ┌─────────────────────────────────────────────────────────────────────────┐│
-│ │ Live Metrics ││
-│ │ ─────────────────────────────────────────────────────────────────────── ││
-│ │ ││
-│ │ CPU Usage Memory Usage Disk Usage Network ││
-│ │ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ││
-│ │ │ 45% │ │ 67% │ │ 34% │ │ ↓ 1.2 │ ││
-│ │ │ ████ │ │ ██████ │ │ ████ │ │ ↑ 0.8 │ ││
-│ │ │ ████ │ │ ██████ │ │ ████ │ │ MB/s │ ││
-│ │ └────────┘ └────────┘ └────────┘ └────────┘ ││
-│ └─────────────────────────────────────────────────────────────────────────┘│
-│ │
-│ ┌─────────────────────────────────────────────────────────────────────────┐│
-│ │ Containers (12 running) [+ Create] ││
-│ │ ─────────────────────────────────────────────────────────────────────── ││
-│ │ Name Image Status CPU Memory Actions ││
-│ │ nginx-proxy nginx:alpine 🟢 Up 2% 45 MB [···] ││
-│ │ app-backend myapp:latest 🟢 Up 12% 234 MB [···] ││
-│ │ postgres-db postgres:15 🟢 Up 5% 512 MB [···] ││
-│ │ redis-cache redis:7 🟢 Up 1% 28 MB [···] ││
-│ └─────────────────────────────────────────────────────────────────────────┘│
-└─────────────────────────────────────────────────────────────────────────────┘
-```
-
-### 7.3 Docker Page Integration
-
-The existing Docker page needs to support server selection:
-
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│ Docker │
-├─────────────────────────────────────────────────────────────────────────────┤
-│ │
-│ Server: [Local (this server) ▼] ← New server selector │
-│ ┌─────────────────────────────────┐ │
-│ │ ⚡ Local (this server) │ │
-│ │ ─────────────────────────────── │ │
-│ │ 🟢 production-server-1 │ │
-│ │ 🟢 production-server-2 │ │
-│ │ 🔴 staging-server (offline) │ │
-│ │ 🟢 dev-server │ │
-│ └─────────────────────────────────┘ │
-│ │
-│ [Containers] [Images] [Volumes] [Networks] [Compose] │
-│ ... (existing Docker UI, now server-aware) │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## 8. Installation & Packaging
-
-### 8.1 Installation Methods
-
-#### Linux - One-liner Install
-```bash
-curl -fsSL https://your-serverkit.com/install.sh | sudo bash -s -- \
- --token "sk_reg_abc123..."
-```
-
-The script will:
-1. Detect Linux distribution (Ubuntu, Debian, CentOS, Fedora, Alpine)
-2. Download appropriate binary
-3. Create service user (`serverkit-agent`)
-4. Install systemd service
-5. Configure firewall (if needed)
-6. Register with ServerKit using token
-7. Start the agent
-
-#### Windows - PowerShell Install
-```powershell
-# Run as Administrator
-irm https://your-serverkit.com/install.ps1 | iex
-Install-ServerKitAgent -Token "sk_reg_abc123..."
-```
-
-The script will:
-1. Download Windows binary
-2. Install to `C:\Program Files\ServerKit Agent\`
-3. Create Windows Service
-4. Configure Windows Firewall
-5. Register with ServerKit
-6. Start the service
-
-#### Docker Install (for containerized servers)
-```bash
-docker run -d \
- --name serverkit-agent \
- --restart unless-stopped \
- -v /var/run/docker.sock:/var/run/docker.sock \
- -e SERVERKIT_TOKEN="sk_reg_abc123..." \
- serverkit/agent:latest
-```
-
-### 8.2 Package Formats
-
-| Platform | Formats |
-|----------|---------|
-| Linux | `.deb`, `.rpm`, `.apk`, static binary |
-| Windows | `.msi`, `.exe` installer, portable `.zip` |
-| macOS | `.pkg`, `.dmg`, Homebrew formula |
-| Container | Docker image (multi-arch) |
-
-### 8.3 Distribution
-
-```
-Binary Naming Convention:
-serverkit-agent-{version}-{os}-{arch}[.ext]
-
-Examples:
-serverkit-agent-1.0.0-linux-amd64
-serverkit-agent-1.0.0-linux-arm64
-serverkit-agent-1.0.0-windows-amd64.exe
-serverkit-agent-1.0.0-darwin-amd64
-serverkit-agent-1.0.0-darwin-arm64
-
-Package Naming:
-serverkit-agent_1.0.0_amd64.deb
-serverkit-agent-1.0.0-1.x86_64.rpm
-serverkit-agent-1.0.0-x64.msi
-```
-
----
-
-## 9. Communication Protocol
-
-### 9.1 Message Format
-
-```typescript
-// Base message structure
-interface AgentMessage {
- type: string;
- id: string; // Unique message ID
- timestamp: number; // Unix timestamp
- signature?: string; // HMAC-SHA256 signature
-}
-
-// Authentication
-interface AuthMessage extends AgentMessage {
- type: 'auth';
- agent_id: string;
- api_key_prefix: string; // "sk_abc123"
- signature: string; // HMAC(agent_id + timestamp, api_secret)
-}
-
-interface AuthResponse extends AgentMessage {
- type: 'auth_ok' | 'auth_fail';
- session_token?: string;
- expires?: number;
- error?: string;
-}
-
-// Heartbeat
-interface HeartbeatMessage extends AgentMessage {
- type: 'heartbeat';
- metrics: {
- cpu_percent: number;
- memory_percent: number;
- disk_percent: number;
- container_count: number;
- container_running: number;
- };
-}
-
-// Commands
-interface CommandMessage extends AgentMessage {
- type: 'command';
- action: string; // e.g., "docker:container:start"
- params: object;
- timeout?: number; // ms
-}
-
-interface CommandResult extends AgentMessage {
- type: 'command_result';
- command_id: string; // References CommandMessage.id
- success: boolean;
- data?: any;
- error?: string;
- duration: number; // ms
-}
-
-// Streaming
-interface StreamSubscribe extends AgentMessage {
- type: 'subscribe';
- channel: string; // e.g., "container:abc123:logs"
-}
-
-interface StreamData extends AgentMessage {
- type: 'stream';
- channel: string;
- data: any;
-}
-```
-
-### 9.2 Command Types
-
-```yaml
-# Docker Container Commands
-docker:container:list:
- params: { all: boolean, filters: object }
- returns: Container[]
-
-docker:container:inspect:
- params: { id: string }
- returns: ContainerInspect
-
-docker:container:create:
- params: { image: string, name?: string, config: ContainerConfig }
- returns: { id: string }
-
-docker:container:start:
- params: { id: string }
- returns: { success: boolean }
-
-docker:container:stop:
- params: { id: string, timeout?: number }
- returns: { success: boolean }
-
-docker:container:restart:
- params: { id: string, timeout?: number }
- returns: { success: boolean }
-
-docker:container:remove:
- params: { id: string, force?: boolean, volumes?: boolean }
- returns: { success: boolean }
-
-docker:container:logs:
- params: { id: string, tail?: number, since?: string, follow?: boolean }
- returns: Stream<string>
-
-docker:container:stats:
- params: { id: string, stream?: boolean }
- returns: ContainerStats | Stream<ContainerStats>
-
-docker:container:exec:
- params: { id: string, cmd: string[], tty?: boolean }
- returns: { exit_code: number, output: string }
-
-# Docker Image Commands
-docker:image:list:
- params: { filters?: object }
- returns: Image[]
-
-docker:image:pull:
- params: { image: string, tag?: string }
- returns: Stream<PullProgress>
-
-docker:image:remove:
- params: { id: string, force?: boolean }
- returns: { success: boolean }
-
-# Docker Compose Commands
-docker:compose:list:
- params: { }
- returns: ComposeStack[]
-
-docker:compose:up:
- params: { project_name: string, compose_file: string, services?: string[] }
- returns: Stream<ComposeProgress>
-
-docker:compose:down:
- params: { project_name: string, volumes?: boolean }
- returns: { success: boolean }
-
-# System Commands
-system:metrics:
- params: { }
- returns: SystemMetrics
-
-system:info:
- params: { }
- returns: SystemInfo
-
-system:processes:
- params: { }
- returns: Process[]
-
-system:exec: # Requires explicit permission
- params: { command: string, args?: string[], timeout?: number }
- returns: { exit_code: number, stdout: string, stderr: string }
-```
-
----
-
-## 10. Feature Breakdown
-
-### 10.1 Core Features (MVP)
-
-| Feature | Description | Priority |
-|---------|-------------|----------|
-| Agent Registration | Register agents with tokens | P0 |
-| Agent Authentication | Secure API key auth | P0 |
-| WebSocket Gateway | Handle agent connections | P0 |
-| Server CRUD | Create, list, update, delete servers | P0 |
-| Basic Metrics | CPU, RAM, disk from agents | P0 |
-| Container List | List containers on remote servers | P0 |
-| Container Actions | Start/stop/restart containers | P0 |
-| Server Status | Online/offline detection | P0 |
-
-### 10.2 Extended Features (v1.1)
-
-| Feature | Description | Priority |
-|---------|-------------|----------|
-| Server Groups | Organize servers into groups | P1 |
-| Tags & Filtering | Tag-based server filtering | P1 |
-| Container Logs | Stream container logs | P1 |
-| Image Management | Pull, list, remove images | P1 |
-| Docker Compose | Deploy compose stacks | P1 |
-| Historical Metrics | Store and view metrics history | P1 |
-| Alerts | Server/container alerts | P1 |
-
-### 10.3 Advanced Features (v1.2+)
-
-| Feature | Description | Priority |
-|---------|-------------|----------|
-| Cross-server Metrics | Compare metrics across servers | P2 |
-| Remote Terminal | SSH-like terminal via agent | P2 |
-| File Manager | Browse files on remote servers | P2 |
-| Deployment Sync | Deploy to multiple servers | P2 |
-| Load Balancing | Distribute apps across servers | P2 |
-| Auto-scaling | Scale containers based on metrics | P3 |
-| Kubernetes Support | Optional K8s cluster management | P3 |
-
----
-
-## 11. Phase Implementation Plan
-
-### Phase 10.1: Foundation (Agent Core) ✅ COMPLETED
-**Duration: ~2-3 weeks**
-
-```
-[x] Design and implement Go agent binary
- [x] Project setup with Go modules
- [x] Configuration loading (YAML)
- [x] Logging system (structured logs)
- [x] WebSocket client with reconnection
- [x] HMAC authentication
- [x] Heartbeat mechanism
- [x] Graceful shutdown handling
-
-[x] Docker integration in agent
- [x] Connect to Docker socket
- [x] Container list/inspect
- [x] Container start/stop/restart
- [x] Basic stats collection
-
-[x] Build pipeline
- [x] Cross-compilation for all platforms (GitHub Actions)
- [x] Version embedding
- [ ] Binary signing (optional - future)
-```
-
-### Phase 10.2: Backend Gateway ✅ COMPLETED
-**Duration: ~2 weeks**
-
-```
-[x] Database models
- [x] Server, ServerGroup models
- [x] ServerMetrics, ServerCommand models
- [x] AgentSession model
- [x] Migrations (auto via SQLAlchemy)
-
-[x] Agent Gateway (WebSocket server)
- [x] SocketIO namespace for agents (/agent)
- [x] Authentication handler
- [x] Session management
- [x] Command routing
- [x] Connection tracking
-
-[x] API endpoints
- [x] Server CRUD
- [x] Registration token generation
- [x] Server status endpoint
- [x] Remote Docker endpoints (50+ routes)
-```
-
-### Phase 10.3: Security Layer ✅ COMPLETED
-**Duration: ~1-2 weeks**
-
-```
-[x] Security implementation
- [x] API key generation and hashing (bcrypt)
- [x] HMAC-SHA256 signature validation
- [x] Session token management
- [x] Permission checking (scope-based)
- [ ] Rate limiting per agent (future)
- [x] Audit logging (ServerCommand model)
-
-[x] Agent security
- [x] Encrypted key storage (AES-256-GCM)
- [x] Command validation
- [x] Permission enforcement
-```
-
-### Phase 10.4: Frontend - Server Management ✅ COMPLETED
-**Duration: ~2 weeks**
-
-```
-[x] Servers page
- [x] Server list view (grid with cards)
- [x] Server cards with live metrics
- [x] Add server modal with permissions
- [x] Installation instructions (Linux/Windows)
- [x] Server detail page (tabbed interface)
- [x] Server settings
-
-[x] Server groups
- [x] Group CRUD UI (modal)
- [x] Group filtering
- [ ] Drag-drop organization (future)
-```
-
-### Phase 10.5: Remote Docker Integration ✅ COMPLETED
-**Duration: ~2 weeks**
-
-```
-[x] Backend: Docker command routing
- [x] Route Docker commands to agents (RemoteDockerService)
- [x] Handle async responses (command results)
- [x] Error handling
-
-[x] Frontend: Docker page updates
- [x] Server selector dropdown (top of page)
- [x] Context-aware Docker UI (ServerContext)
- [x] Real-time container updates
-
-[x] Agent: Full Docker support
- [x] All container operations
- [x] Image operations
- [x] Volume/network listing
-```
-
-### Phase 10.6: Monitoring & Metrics ✅ COMPLETE
-**Duration: ~2 weeks**
-
-```
-[x] Real-time metrics
- [x] Agent metrics streaming (heartbeat)
- [x] WebSocket to frontend (SocketIO)
- [x] Live dashboard updates
-
-[x] Historical metrics
- [x] Metrics storage (ServerMetrics model)
- [x] Retention policies (7 days raw, configurable)
- [x] Aggregation queries (hourly, daily)
- [x] ServerMetricsService with cleanup
- [x] API endpoints for history and aggregated data
- [x] Multi-server comparison API
-
-[x] Cross-server dashboard
- [x] Overview page (Servers.jsx)
- [x] Metric comparison (server cards)
- [x] Health grid view
-```
-
-### Phase 10.7: Installation & Distribution ✅ COMPLETE
-**Duration: ~1-2 weeks**
-
-```
-[x] Build automation
- [x] GitHub Actions workflow (agent-release.yml)
- [x] Linux amd64/arm64 builds
- [x] Windows amd64 builds
- [x] Automatic releases on tag
-
-[x] Installation scripts
- [x] Linux install script (bash) - created
- [x] Windows install script (PowerShell) - created
- [x] Installation endpoint in backend
- [x] Docker image (Dockerfile + docker-compose.yml)
-
-[x] Package building
- [x] .deb packages (packaging/deb/build.sh)
- [x] .rpm packages (packaging/rpm/build.sh)
- [x] .msi installer (packaging/msi/Product.wxs + build.ps1)
- [ ] Homebrew formula (future)
-
-[x] Auto-update system
- [x] Version checking endpoint
- [x] Auto-update mechanism in agent
- [x] Manual update command (`serverkit-agent update`)
-
-[x] Distribution
- [x] Download page in UI
-```
-
-### Phase 10.8: Advanced Features ✅ COMPLETE
-**Duration: ~3-4 weeks**
-
-```
-[x] Docker Compose on remote servers
- [x] Agent: Compose methods (list, ps, up, down, logs, restart, pull)
- [x] Backend: RemoteDockerService compose methods
- [x] Backend: API endpoints for compose operations
- [x] Frontend: API methods for compose
- [x] Frontend: ComposeTab in Docker page
- [x] Frontend: ComposeLogsModal for viewing logs
- [ ] Compose file editor (future)
-
-[x] Container logs streaming
- [x] Real-time log streaming via agent
- [x] Backend endpoint for remote logs
- [x] Frontend integration with server context
- [ ] Log search/filter (future)
- [ ] Download logs (future)
-
-[x] Remote terminal
- [x] PTY support in agent (creack/pty library)
- [x] Terminal manager for session management
- [x] Backend terminal service and API endpoints
- [x] Frontend xterm.js terminal component (RemoteTerminal.jsx)
-```
-
----
-
-## 12. Risk Assessment
-
-### Technical Risks
-
-| Risk | Impact | Likelihood | Mitigation |
-|------|--------|------------|------------|
-| WebSocket scalability | High | Medium | Use Redis pub/sub for horizontal scaling |
-| Agent memory leaks | Medium | Low | Extensive testing, memory profiling |
-| Network latency | Medium | Medium | Async commands, timeouts, retry logic |
-| Docker API changes | Low | Low | Pin Docker SDK version, integration tests |
-
-### Security Risks
-
-| Risk | Impact | Likelihood | Mitigation |
-|------|--------|------------|------------|
-| Stolen API keys | Critical | Medium | Key rotation, IP whitelist, anomaly detection |
-| Man-in-the-middle | Critical | Low | TLS mandatory, certificate pinning option |
-| Agent compromise | Critical | Low | Sandboxing, minimal privileges, audit logs |
-| Replay attacks | High | Medium | Timestamps, nonces, short-lived tokens |
-
-### Operational Risks
-
-| Risk | Impact | Likelihood | Mitigation |
-|------|--------|------------|------------|
-| Mass disconnect | High | Low | Graceful degradation, cached state |
-| Database growth | Medium | High | Metrics retention policy, archiving |
-| Support burden | Medium | High | Good documentation, self-service tools |
-
----
-
-## 13. Success Metrics
-
-| Metric | Target |
-|--------|--------|
-| Agent installation time | < 5 minutes |
-| Agent memory usage | < 50 MB |
-| Command latency | < 500ms (local network) |
-| Max servers per instance | 100+ |
-| Uptime | 99.9% |
-| User satisfaction | > 4.5/5 rating |
-
----
-
-## 14. Future Considerations
-
-### Potential Extensions
-- **Kubernetes Support**: Manage K8s clusters alongside Docker
-- **Multi-tenancy**: Multiple users/teams managing different server sets
-- **Terraform Integration**: Infrastructure as Code support
-- **Ansible Playbooks**: Configuration management
-- **CI/CD Integration**: Deploy from GitHub Actions, GitLab CI
-- **Mobile App**: Monitor servers from mobile devices
-- **Slack/Teams Bot**: Manage servers via chat commands
-
-### Not In Scope (for now)
-- Bare metal provisioning
-- Cloud provider integration (AWS, GCP, Azure)
-- Network topology management
-- DNS management
-- Load balancer configuration
-
----
-
-## Appendix A: Agent Command Reference
-
-```
-serverkit-agent [command] [flags]
-
-Commands:
- start Start the agent service
- stop Stop the agent service
- status Show agent status
- register Register with ServerKit (interactive)
- config Show/edit configuration
- logs View agent logs
- version Show version information
- update Check for and install updates
- uninstall Remove agent from system
-
-Flags:
- --config, -c Path to config file
- --debug, -d Enable debug logging
- --token, -t Registration token (for register command)
- --server, -s ServerKit URL (for register command)
-
-Examples:
- serverkit-agent register --token "sk_reg_abc123" --server "https://serverkit.example.com"
- serverkit-agent status
- serverkit-agent logs --tail 100
-```
-
----
-
-## Appendix B: Configuration Reference
-
-```yaml
-# Full agent configuration reference
-# Location: /etc/serverkit-agent/config.yaml (Linux)
-# C:\ProgramData\ServerKit\Agent\config.yaml (Windows)
-
-# ServerKit connection
-server:
- url: wss://your-serverkit.example.com/agent/ws
- reconnect_interval: 5s
- max_reconnect_interval: 5m
- ping_interval: 30s
-
-# Agent identity
-agent:
- id: "auto-generated-uuid"
- name: "server-display-name"
-
-# Authentication (auto-generated)
-auth:
- key_file: /etc/serverkit-agent/agent.key
-
-# Feature toggles
-features:
- docker: true
- metrics: true
- logs: true
- file_access: false
- exec: false
-
-# Metrics collection
-metrics:
- enabled: true
- interval: 10s
- include_per_cpu: true
- include_docker_stats: true
-
-# Docker configuration
-docker:
- socket: /var/run/docker.sock # Linux
- # socket: npipe:////./pipe/docker_engine # Windows
- timeout: 30s
-
-# Security settings
-security:
- allowed_paths: []
- blocked_commands: []
- max_exec_timeout: 300s
-
-# Logging
-logging:
- level: info # debug, info, warn, error
- file: /var/log/serverkit-agent/agent.log
- max_size: 100MB
- max_backups: 5
- max_age: 30 # days
- compress: true
-```
-
----
-
-*This document is a living specification and will be updated as implementation progresses.*
-
-**Document Version**: 1.2.0
-**Last Updated**: 2026-01-22
-**Author**: ServerKit Team
diff --git a/SERVER_SECURITY_PLAN.md b/SERVER_SECURITY_PLAN.md
deleted file mode 100644
index 5f579d62..00000000
--- a/SERVER_SECURITY_PLAN.md
+++ /dev/null
@@ -1,330 +0,0 @@
-Implement the following plan:
-
- # Security Features Implementation Plan
-
- ## Overview
- Implement four security checklist items for ServerKit agent system:
- 1. API Key Rotation
- 2. IP Allowlisting
- 3. Anomaly Detection
- 4. Replay Protection (Nonces)
-
- ---
-
- ## Phase 1: Foundation & Replay Protection
-
- ### 1.1 Add Crypto Utilities
- **File:** `backend/app/utils/crypto.py` (NEW)
-
- ```python
- from cryptography.fernet import Fernet
- import os
-
- def get_encryption_key():
- key = os.environ.get('SERVERKIT_ENCRYPTION_KEY')
- if not key:
- raise ValueError("SERVERKIT_ENCRYPTION_KEY not set")
- return key.encode()
-
- def encrypt_secret(plaintext: str) -> str
- def decrypt_secret(encrypted: str) -> str
- ```
-
- ### 1.2 Add IP Utilities
- **File:** `backend/app/utils/ip_utils.py` (NEW)
-
- ```python
- def is_ip_allowed(client_ip: str, allowed_list: list) -> bool:
- """Supports: single IP, CIDR (192.168.1.0/24), wildcards (192.168.1.*)"""
- ```
-
- ### 1.3 Update Server Model
- **File:** `backend/app/models/server.py`
-
- Add fields:
- ```python
- api_secret_encrypted = db.Column(db.Text) # Fernet-encrypted api_secret for signature
- verification
- api_key_pending_hash = db.Column(db.String(256)) # For key rotation
- api_key_pending_prefix = db.Column(db.String(12))
- api_key_rotation_expires = db.Column(db.DateTime)
- ```
-
- ### 1.4 Update Registration to Store Encrypted Secret
- **File:** `backend/app/api/servers.py`
-
- In `register_agent()`:
- - After generating credentials, encrypt and store `api_secret`
- - Existing agents without encrypted secret continue working (backward compatible)
-
- ### 1.5 Implement Full Signature Verification
- **File:** `backend/app/services/agent_registry.py`
-
- Update `verify_agent_auth()`:
- ```python
- def verify_agent_auth(self, agent_id, api_key_prefix, signature, timestamp, nonce=None):
- # 1. Check timestamp (existing 5-minute window)
- # 2. Find server by agent_id
- # 3. Verify api_key_prefix (existing)
- # 4. NEW: Verify HMAC signature if api_secret_encrypted exists
- # 5. NEW: Check nonce not already used (replay protection)
- ```
-
- ### 1.6 Add Nonce Tracking Service
- **File:** `backend/app/services/nonce_service.py` (NEW)
-
- ```python
- class NonceService:
- """Track used nonces to prevent replay attacks (5-minute TTL)."""
-
- def check_and_record(self, server_id: str, nonce: str) -> bool:
- """Returns True if valid, False if replay detected."""
- ```
-
- ---
-
- ## Phase 2: IP Allowlisting
-
- ### 2.1 Enforce IP Check in Gateway
- **File:** `backend/app/agent_gateway.py`
-
- In `on_auth()` after authentication:
- ```python
- if server.allowed_ips and len(server.allowed_ips) > 0:
- if not is_ip_allowed(request.remote_addr, server.allowed_ips):
- emit('auth_fail', {'error': 'IP address not allowed'})
- # Log security event
- disconnect()
- return
- ```
-
- ### 2.2 Add API Endpoint
- **File:** `backend/app/api/servers.py`
-
- ```
- PUT /api/servers/<server_id>/allowed-ips
- Body: { "allowed_ips": ["192.168.1.0/24", "10.0.0.5"] }
-
- GET /api/servers/<server_id>/connection-info
- Response: { "connected": bool, "ip_address": str, "connected_since": str }
- ```
-
- ### 2.3 Add Frontend UI
- **File:** `frontend/src/pages/ServerDetail.jsx`
-
- In SettingsTab, add "IP Allowlist" section:
- - Show current connection IP
- - List of allowed IPs with add/remove
- - Support CIDR notation
- - Warning if current IP would be blocked
-
- ### 2.4 Add Frontend API Methods
- **File:** `frontend/src/services/api.js`
-
- ```javascript
- async updateAllowedIPs(serverId, allowedIPs)
- async getConnectionInfo(serverId)
- ```
-
- ---
-
- ## Phase 3: Anomaly Detection
-
- ### 3.1 Create Security Alert Model
- **File:** `backend/app/models/security_alert.py` (NEW)
-
- ```python
- class SecurityAlert(db.Model):
- id = db.Column(db.String(36), primary_key=True)
- server_id = db.Column(db.String(36), ForeignKey('servers.id'))
- alert_type = db.Column(db.String(50)) # auth_failure, rate_limit, new_ip,
- suspicious_pattern
- severity = db.Column(db.String(20)) # info, warning, critical
- source_ip = db.Column(db.String(45))
- details = db.Column(db.JSON)
- status = db.Column(db.String(20), default='open') # open, acknowledged, resolved
- created_at = db.Column(db.DateTime)
- ```
-
- ### 3.2 Create Anomaly Detection Service
- **File:** `backend/app/services/anomaly_detection_service.py` (NEW)
-
- ```python
- class AnomalyDetectionService:
- THRESHOLDS = {
- 'auth_failures_per_minute': 5,
- 'auth_failures_per_hour': 20,
- 'commands_per_minute': 100,
- }
-
- def track_auth_attempt(self, server_id, success, ip_address)
- def track_command(self, server_id, command_type)
- def check_new_ip(self, server_id, ip_address) # Alert on first connection from new IP
- def get_alerts(self, server_id=None, status='open')
- ```
-
- ### 3.3 Integrate Detection in Gateway
- **File:** `backend/app/agent_gateway.py`
-
- - Call `track_auth_attempt()` on auth success/failure
- - Call `check_new_ip()` on successful connection
- - Call `track_command()` when routing commands
-
- ### 3.4 Add API Endpoints
- **File:** `backend/app/api/servers.py`
-
- ```
- GET /api/servers/<server_id>/security/alerts
- GET /api/servers/security/alerts # All servers
- POST /api/servers/security/alerts/<alert_id>/acknowledge
- POST /api/servers/security/alerts/<alert_id>/resolve
- ```
-
- ### 3.5 Add Frontend UI
- **File:** `frontend/src/pages/ServerDetail.jsx`
-
- Add "Security" tab or section showing:
- - Active alerts with severity badges
- - Acknowledge/resolve buttons
- - Recent security events
-
- ### 3.6 Add Frontend API Methods
- **File:** `frontend/src/services/api.js`
-
- ```javascript
- async getSecurityAlerts(serverId)
- async acknowledgeAlert(alertId)
- async resolveAlert(alertId)
- ```
-
- ---
-
- ## Phase 4: API Key Rotation
-
- ### 4.1 Add Rotation Endpoint
- **File:** `backend/app/api/servers.py`
-
- ```
- POST /api/servers/<server_id>/rotate-api-key
- ```
- - Generate new api_key and api_secret
- - Store in pending fields (api_key_pending_hash, etc.)
- - Set 5-minute expiry
- - Send `credential_update` message to connected agent
- - Return { success: true, rotation_id: str }
-
- ### 4.2 Add WebSocket Message Handlers
- **File:** `backend/app/agent_gateway.py`
-
- Handle `credential_update_ack` from agent:
- - Verify rotation_id matches
- - Move pending credentials to active
- - Clear pending fields
- - Log rotation complete
-
- ### 4.3 Update Agent to Handle Credential Rotation
- **File:** `agent/internal/agent/agent.go`
-
- Add handler for `credential_update` message:
- ```go
- func (a *Agent) handleCredentialUpdate(data CredentialUpdateMessage) {
- // 1. Decrypt and validate new credentials
- // 2. Save to agent.key file
- // 3. Update authenticator with new credentials
- // 4. Send credential_update_ack
- }
- ```
-
- ### 4.4 Add Protocol Constants
- **File:** `agent/pkg/protocol/messages.go`
-
- ```go
- const (
- TypeCredentialUpdate = "credential_update"
- TypeCredentialUpdateAck = "credential_update_ack"
- )
- ```
-
- ### 4.5 Add Frontend UI
- **File:** `frontend/src/pages/ServerDetail.jsx`
-
- In SettingsTab Security section:
- - "Rotate API Key" button
- - Confirmation modal
- - Status indicator during rotation
- - Last rotation timestamp display
-
- ### 4.6 Add Frontend API Method
- **File:** `frontend/src/services/api.js`
-
- ```javascript
- async rotateAPIKey(serverId)
- ```
-
- ---
-
- ## File Summary
-
- | File | Action | Changes |
- |------|--------|---------|
- | `backend/app/utils/crypto.py` | CREATE | Fernet encryption utilities |
- | `backend/app/utils/ip_utils.py` | CREATE | IP matching utilities |
- | `backend/app/models/server.py` | MODIFY | Add 4 new fields |
- | `backend/app/models/security_alert.py` | CREATE | SecurityAlert model |
- | `backend/app/services/nonce_service.py` | CREATE | Nonce tracking |
- | `backend/app/services/anomaly_detection_service.py` | CREATE | Anomaly detection |
- | `backend/app/services/agent_registry.py` | MODIFY | Full signature verification |
- | `backend/app/agent_gateway.py` | MODIFY | IP enforcement, anomaly tracking |
- | `backend/app/api/servers.py` | MODIFY | 6+ new endpoints |
- | `agent/pkg/protocol/messages.go` | MODIFY | Add credential update constants |
- | `agent/internal/agent/agent.go` | MODIFY | Handle credential rotation |
- | `frontend/src/services/api.js` | MODIFY | Add 6 new API methods |
- | `frontend/src/pages/ServerDetail.jsx` | MODIFY | Add Security section in settings |
-
- ---
-
- ## Environment Setup
-
- Add to `.env`:
- ```
- SERVERKIT_ENCRYPTION_KEY=<generate with: python -c "from cryptography.fernet import Fernet;
- print(Fernet.generate_key().decode())">
- ```
-
- ---
-
- ## Verification
-
- 1. **Replay Protection:**
- - Register new agent, verify `api_secret_encrypted` is stored
- - Replay captured auth message, verify rejection
-
- 2. **IP Allowlisting:**
- - Set allowed_ips for server
- - Connect from allowed IP - should work
- - Connect from blocked IP - should fail with "IP address not allowed"
-
- 3. **Anomaly Detection:**
- - Trigger 5+ failed auth attempts, verify alert created
- - Connect from new IP, verify info alert
- - Check alerts appear in UI
-
- 4. **API Key Rotation:**
- - Click rotate in UI
- - Verify agent receives new credentials
- - Verify agent continues working with new key
- - Verify old key no longer works
-
- ---
-
- ## Security Notes
-
- - `SERVERKIT_ENCRYPTION_KEY` must be securely generated and stored
- - Existing agents without encrypted secret continue working (backward compatible)
- - Nonce tracking uses in-memory storage (Redis recommended for production)
- - All security events logged to SecurityAlert model
-
-
- If you need specific details from before exiting plan mode (like exact code snippets, error
- messages, or content you generated), read the full transcript at: C:\Users\Juan\.claude\pr
- ojects\C--Users-Juan-Documents-GitHub-ServerKit\11807e92-eec1-4123-8510-9b549a358667.jsonl
\ No newline at end of file
diff --git a/backend/app/api/auth.py b/backend/app/api/auth.py
index 72291799..e3df6f48 100644
--- a/backend/app/api/auth.py
+++ b/backend/app/api/auth.py
@@ -99,13 +99,16 @@ def login():
if not data:
return jsonify({'error': 'No data provided'}), 400
- email = data.get('email')
+ login_id = data.get('email') # Can be email or username
password = data.get('password')
- if not all([email, password]):
- return jsonify({'error': 'Missing email or password'}), 400
+ if not all([login_id, password]):
+ return jsonify({'error': 'Missing email/username or password'}), 400
- user = User.query.filter_by(email=email).first()
+ # Try to find user by email or username
+ user = User.query.filter(
+ (User.email == login_id) | (User.username == login_id)
+ ).first()
# Check if account is locked
if user and user.is_locked:
@@ -120,7 +123,7 @@ def login():
user.record_failed_login()
AuditService.log_login(user.id, success=False, details={'reason': 'invalid_password'})
db.session.commit()
- return jsonify({'error': 'Invalid email or password'}), 401
+ return jsonify({'error': 'Invalid username/email or password'}), 401
if not user.is_active:
AuditService.log_login(user.id, success=False, details={'reason': 'account_deactivated'})
diff --git a/backend/run.py b/backend/run.py
index df4e7246..351655da 100644
--- a/backend/run.py
+++ b/backend/run.py
@@ -1,5 +1,10 @@
import os
import sys
+from dotenv import load_dotenv
+
+# Load .env file before creating app
+load_dotenv()
+
from app import create_app, get_socketio
app = create_app()
@@ -18,4 +23,13 @@ if __name__ == '__main__':
sys.exit(1)
# Use SocketIO to run the app (supports WebSocket) - only in development
- socketio.run(app, host='0.0.0.0', port=port, debug=debug)
+ # use_reloader with stat polling for WSL compatibility
+ socketio.run(
+ app,
+ host='0.0.0.0',
+ port=port,
+ debug=debug,
+ allow_unsafe_werkzeug=True,
+ use_reloader=True,
+ reloader_type='stat' # Use polling instead of inotify (for WSL)
+ )
diff --git a/dev.bat b/dev.bat
deleted file mode 100644
index a2a8d9f5..00000000
--- a/dev.bat
+++ /dev/null
@@ -1,65 +0,0 @@
-@echo off
-REM ServerKit Local Development Helper for Windows
-REM Usage: dev.bat [command]
-
-if "%1"=="" goto help
-if "%1"=="up" goto up
-if "%1"=="down" goto down
-if "%1"=="logs" goto logs
-if "%1"=="shell" goto shell
-if "%1"=="reset" goto reset
-if "%1"=="help" goto help
-goto help
-
-:up
-echo Starting ServerKit development environment...
-docker compose -f docker-compose.dev.yml up --build -d
-echo.
-echo ServerKit is starting up:
-echo Frontend: http://localhost:3000
-echo Backend: http://localhost:5000
-echo.
-echo Run 'dev.bat logs' to see logs
-goto end
-
-:down
-echo Stopping ServerKit development environment...
-docker compose -f docker-compose.dev.yml down
-goto end
-
-:logs
-docker compose -f docker-compose.dev.yml logs -f
-goto end
-
-:shell
-echo Opening shell in backend container...
-docker exec -it serverkit-backend-dev /bin/bash
-goto end
-
-:reset
-echo Resetting development environment (removing volumes)...
-docker compose -f docker-compose.dev.yml down -v
-echo Done. Run 'dev.bat up' to start fresh.
-goto end
-
-:help
-echo.
-echo ServerKit Development Helper
-echo ============================
-echo.
-echo Usage: dev.bat [command]
-echo.
-echo Commands:
-echo up Start development environment
-echo down Stop development environment
-echo logs View logs (Ctrl+C to exit)
-echo shell Open bash shell in backend container
-echo reset Stop and remove all data (fresh start)
-echo help Show this help message
-echo.
-echo Note: System management features (PHP, firewall, etc.)
-echo won't work in Docker mode. Use WSL for full testing.
-echo.
-goto end
-
-:end
diff --git a/frontend/.env.development b/frontend/.env.development
new file mode 100644
index 00000000..8ed0e6b4
--- /dev/null
+++ b/frontend/.env.development
@@ -0,0 +1 @@
+VITE_API_URL=http://localhost:5000
diff --git a/frontend/src/pages/Login.jsx b/frontend/src/pages/Login.jsx
index 34c4454b..96652387 100644
--- a/frontend/src/pages/Login.jsx
+++ b/frontend/src/pages/Login.jsx
@@ -234,14 +234,15 @@ const Login = () => {
<form onSubmit={handleSubmit}>
<div className="form-group">
- <label htmlFor="email">Email</label>
+ <label htmlFor="email">Username or Email</label>
<input
- type="email"
+ type="text"
id="email"
value={email}
onChange={(e) => setEmail(e.target.value)}
- placeholder="[email protected]"
+ placeholder="admin or [email protected]"
required
+ autoComplete="username"
/>
</div>
diff --git a/frontend/vite.config.js b/frontend/vite.config.js
index 92babc14..848cb8fd 100644
--- a/frontend/vite.config.js
+++ b/frontend/vite.config.js
@@ -4,4 +4,11 @@ import react from '@vitejs/plugin-react'
// https://vitejs.dev/config/
export default defineConfig({
plugins: [react()],
+ server: {
+ // Enable polling for WSL (Windows filesystem doesn't support inotify)
+ watch: {
+ usePolling: true,
+ interval: 1000,
+ },
+ },
})
diff --git a/scripts/dev/dev.bat b/scripts/dev/dev.bat
new file mode 100644
index 00000000..adbf119c
--- /dev/null
+++ b/scripts/dev/dev.bat
@@ -0,0 +1,59 @@
+@echo off
+REM ServerKit Docker Dev Helper
+REM Usage: scripts\dev\dev.bat [command]
+
+REM Get project root (two levels up from this script)
+set "SCRIPT_DIR=%~dp0"
+set "PROJECT_ROOT=%SCRIPT_DIR%..\.."
+pushd "%PROJECT_ROOT%"
+
+if "%1"=="" goto help
+if "%1"=="up" goto up
+if "%1"=="down" goto down
+if "%1"=="logs" goto logs
+if "%1"=="shell" goto shell
+if "%1"=="reset" goto reset
+goto help
+
+:up
+echo Starting ServerKit (Docker)...
+docker compose -f docker-compose.dev.yml up --build -d
+echo.
+echo Frontend: http://localhost:3000
+echo Backend: http://localhost:5000
+echo.
+goto end
+
+:down
+docker compose -f docker-compose.dev.yml down
+goto end
+
+:logs
+docker compose -f docker-compose.dev.yml logs -f
+goto end
+
+:shell
+docker exec -it serverkit-backend-dev /bin/bash
+goto end
+
+:reset
+docker compose -f docker-compose.dev.yml down -v
+echo Run 'dev.bat up' to start fresh.
+goto end
+
+:help
+echo.
+echo Usage: scripts\dev\dev.bat [command]
+echo.
+echo up Start containers
+echo down Stop containers
+echo logs View logs
+echo shell Shell into backend
+echo reset Reset all data
+echo.
+echo Note: Use WSL for full system feature testing.
+echo.
+goto end
+
+:end
+popd
diff --git a/dev-setup.sh b/scripts/dev/setup-linux.sh
similarity index 100%
rename from dev-setup.sh
rename to scripts/dev/setup-linux.sh
diff --git a/scripts/dev/setup-wsl.sh b/scripts/dev/setup-wsl.sh
new file mode 100644
index 00000000..bb6bd149
--- /dev/null
+++ b/scripts/dev/setup-wsl.sh
@@ -0,0 +1,105 @@
+#!/bin/bash
+# ServerKit WSL Development Setup
+# Run: ./scripts/dev/setup-wsl.sh
+
+set -e
+
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+cd "$PROJECT_ROOT"
+
+echo "============================================"
+echo " ServerKit Dev Setup"
+echo "============================================"
+echo ""
+
+echo -e "${YELLOW}[1/6] Installing base dependencies...${NC}"
+sudo apt update
+sudo apt install -y python3.11 python3.11-venv python3-pip nginx docker.io docker-compose git curl lsof ca-certificates gnupg
+sudo usermod -aG docker $USER 2>/dev/null || true
+echo -e "${GREEN}Done!${NC}"
+
+echo -e "${YELLOW}[2/6] Installing Node.js 20...${NC}"
+# Install Node.js 20 from NodeSource (Ubuntu default is too old)
+if ! node --version 2>/dev/null | grep -q "v20\|v21\|v22"; then
+ curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+ sudo apt install -y nodejs
+fi
+echo "Node.js $(node --version)"
+echo -e "${GREEN}Done!${NC}"
+
+echo -e "${YELLOW}[3/6] Enabling systemd...${NC}"
+if ! grep -q "systemd=true" /etc/wsl.conf 2>/dev/null; then
+ echo -e "[boot]\nsystemd=true" | sudo tee /etc/wsl.conf > /dev/null
+ echo -e "${YELLOW}Note: Run 'wsl --shutdown' after setup for systemd.${NC}"
+fi
+echo -e "${GREEN}Done!${NC}"
+
+echo -e "${YELLOW}[4/6] Setting up backend...${NC}"
+cd "$PROJECT_ROOT/backend"
+python3.11 -m venv venv
+source venv/bin/activate
+pip install --upgrade pip -q
+pip install -r requirements.txt -q
+
+# Create instance directory in WSL-native location (SQLite doesn't work on /mnt/c)
+mkdir -p ~/.serverkit
+mkdir -p instance
+
+# Create .env with WSL-compatible database path
+cat > .env << EOF
+FLASK_ENV=development
+FLASK_DEBUG=1
+SECRET_KEY=dev-secret-key
+DATABASE_URL=sqlite:///$HOME/.serverkit/serverkit.db
+EOF
+echo -e "${GREEN}Done!${NC}"
+
+echo -e "${YELLOW}[5/6] Setting up frontend...${NC}"
+cd "$PROJECT_ROOT/frontend"
+npm install
+[ ! -f .env.development ] && echo "VITE_API_URL=http://localhost:5000" > .env.development
+echo -e "${GREEN}Done!${NC}"
+
+echo -e "${YELLOW}[6/6] Creating admin user...${NC}"
+cd "$PROJECT_ROOT/backend"
+source venv/bin/activate
+python3 << 'PYTHON'
+import sys, os
+sys.path.insert(0, os.getcwd())
+try:
+ from app import create_app, db
+ from app.models.user import User
+ from werkzeug.security import generate_password_hash
+ app = create_app()
+ with app.app_context():
+ db.create_all()
+ admin = User.query.filter_by(username='admin').first()
+ if admin:
+ admin.password = generate_password_hash('admin')
+ else:
+ admin = User(username='admin', email='admin@localhost', password=generate_password_hash('admin'), is_admin=True)
+ db.session.add(admin)
+ db.session.commit()
+ print("Admin user ready!")
+except Exception as e:
+ print(f"Could not create admin: {e}")
+PYTHON
+echo -e "${GREEN}Done!${NC}"
+
+echo ""
+echo "============================================"
+echo -e "${GREEN} Ready!${NC}"
+echo "============================================"
+echo ""
+echo " Login: admin / admin"
+echo " DB: ~/.serverkit/serverkit.db"
+echo ""
+echo " Start: ./scripts/dev/start.sh"
+echo ""
+echo " Open: http://localhost:5173"
+echo ""
diff --git a/scripts/dev/start.sh b/scripts/dev/start.sh
new file mode 100644
index 00000000..e0bf2607
--- /dev/null
+++ b/scripts/dev/start.sh
@@ -0,0 +1,24 @@
+#!/bin/bash
+# Start both backend and frontend
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+echo "Starting ServerKit..."
+echo " Backend: http://localhost:5000"
+echo " Frontend: http://localhost:5173"
+echo ""
+
+cd "$PROJECT_ROOT/backend"
+source venv/bin/activate
+python run.py &
+BACKEND_PID=$!
+
+sleep 2
+
+cd "$PROJECT_ROOT/frontend"
+npm run dev &
+FRONTEND_PID=$!
+
+trap "kill $BACKEND_PID $FRONTEND_PID 2>/dev/null; exit" INT TERM
+wait