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.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
Add unified dev scripts and improve login UX
Juan Denis6bcbcab56a2f
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 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.gitcd ServerKitgit remote add upstream https://github.com/jhd3197/ServerKit.git```------## Development Setup-### Backend Setup```bash-# Create virtual environmentcd backendpython -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\activatepip 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 serverpython run.py```-The backend will be available at `http://localhost:5000`.-### Frontend Setup```bash-# In a new terminalcd frontend--# Install dependenciesnpm install--# Run development servernpm 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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 Teamdiff --git a/SERVER_SECURITY_PLAN.md b/SERVER_SECURITY_PLAN.mddeleted file mode 100644index 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 filediff --git a/backend/app/api/auth.py b/backend/app/api/auth.pyindex 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 usernamepassword = 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 lockedif 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'}), 401if not user.is_active:AuditService.log_login(user.id, success=False, details={'reason': 'account_deactivated'})diff --git a/backend/run.py b/backend/run.pyindex df4e7246..351655da 100644--- a/backend/run.py+++ b/backend/run.py@@ -1,5 +1,10 @@import osimport sys+from dotenv import load_dotenv++# Load .env file before creating app+load_dotenv()+from app import create_app, get_socketioapp = 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.batdeleted file mode 100644index 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--:enddiff --git a/frontend/.env.development b/frontend/.env.developmentnew file mode 100644index 00000000..8ed0e6b4--- /dev/null+++ b/frontend/.env.development@@ -0,0 +1 @@+VITE_API_URL=http://localhost:5000diff --git a/frontend/src/pages/Login.jsx b/frontend/src/pages/Login.jsxindex 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.jsindex 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.batnew file mode 100644index 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+popddiff --git a/dev-setup.sh b/scripts/dev/setup-linux.shsimilarity index 100%rename from dev-setup.shrename to scripts/dev/setup-linux.shdiff --git a/scripts/dev/setup-wsl.sh b/scripts/dev/setup-wsl.shnew file mode 100644index 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.shnew file mode 100644index 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