mirror of
https://github.com/jhd3197/ServerKit.git
synced 2026-10-28 23:57:58 +09:00
Juan DenisandClaude Opus 4.8
eab1a35794
dev was ~149 commits ahead of the last release with no changelog and several stale docs. This brings the user-facing docs in line with what actually ships. New: - CHANGELOG.md — curates the unreleased panel work (agent fleet, plugins, status pages, cloud provisioning, RHEL support, installer hardening). - agent/CHANGELOG.md — the agent release workflow links to this on every published release; it was a broken link. Now documents the agent's independent release line. - SECURITY.md — vulnerability reporting policy + agent trust model (agent.key is host-equivalent; Features.Exec off by default; single-worker). Fixes: - Stale version stamps: docs/README.md and docs/API.md said 0.9.0 -> 1.6.7. - Supported OS: README/INSTALLATION said Ubuntu/Debian only; installer also covers Fedora and RHEL/Rocky/AlmaLinux. - Dead links/placeholders: API.md wiki link, INSTALLATION.md "yourusername". - Windows agent + short-code pairing were undocumented; added to README, agent/README.md, and docs/pairing.md (incl. corrected host-stable credential-key derivation — USERNAME was dropped in agent 1.6.14). - Documented the single gevent-websocket-worker deployment constraint in CLAUDE.md and docs/ARCHITECTURE.md. - CONTRIBUTING.md: removed reference to a non-existent frontend test suite. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
16 KiB
16 KiB
ServerKit Architecture
Deep dive into how ServerKit connects domains, apps, containers, and databases.
Table of Contents
- System Overview
- Request Flow
- Template System
- Port Allocation
- Database Linking
- Workflow Automation
- Environment Pipeline
- File Paths
System Overview
┌─────────────────────────────────────────────────────────────┐
│ INTERNET │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ YOUR SERVER │
│ ┌───────────────────────────────────────────────────────────────────────────────────────────────┐ │
│ │ NGINX (Reverse Proxy) │ │
│ │ Port 80 / 443 │ │
│ │ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ app1.com │ │ app2.com │ │ api.app3.com │ │ Private URLs │ │ │
│ │ │ :443 │ │ :443 │ │ :443 │ │ /p/abc123 │ │ │
│ │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ │
│ └──────────┼───────────────────┼───────────────────┼───────────────────┼────────────────────────┘ │
│ │ │ │ │ │
│ │ proxy_pass │ proxy_pass │ proxy_pass │ proxy_pass │
│ ▼ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐ │
│ │ DOCKER CONTAINERS │ │
│ │ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ WordPress │ │ Flask │ │ Node.js │ │ Custom │ │ │
│ │ │ Port 8001 │ │ Port 8002 │ │ Port 8003 │ │ Port 8004 │ │ │
│ │ │ │ │ │ │ │ │ │ │ │
│ │ │ ┌──────────┐ │ │ ┌──────────┐ │ │ ┌──────────┐ │ │ ┌──────────┐ │ │ │
│ │ │ │ Apache │ │ │ │ Gunicorn │ │ │ │ PM2 │ │ │ │ Your │ │ │ │
│ │ │ │ PHP-FPM │ │ │ │ Python │ │ │ │ Express │ │ │ │ App │ │ │ │
│ │ │ └──────────┘ │ │ └──────────┘ │ │ └──────────┘ │ │ └──────────┘ │ │ │
│ │ └──────┬───────┘ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ │ │ │ │
│ └──────────┼──────────────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐ │
│ │ DATABASES │ │
│ │ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ MySQL │ │ PostgreSQL │ │ Redis │ │ MongoDB │ │ │
│ │ │ Port 3306 │ │ Port 5432 │ │ Port 6379 │ │ Port 27017 │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────────────────────────────┘
Request Flow
What happens when a user visits your app:
User Request What Happens
─────────────────────────────────────────────────────────────────────────────────
Browser 1. DNS resolves app1.com to your server IP
│
▼
┌─────────┐ 2. Request hits Nginx on port 80/443
│ Nginx │ Nginx checks server_name directives
│ :80/443 │ Matches "app1.com" → proxy_pass http://127.0.0.1:8001
└────┬────┘
│
▼
┌─────────┐ 3. Nginx forwards request to Docker container
│ Docker │ Container receives request on internal port
│ :8001 │ App processes and returns response
└────┬────┘
│
▼
┌─────────┐ 4. Response flows back through Nginx
│ Response│ SSL termination handled by Nginx
│ 200 OK │ User sees the page
└─────────┘
Template System
Template → App → Domain Lifecycle
┌─────────────────────────────────────────────────────────────────────────────────┐
│ TEMPLATE LIBRARY │
│ /etc/serverkit/templates/ │
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │WordPress│ │ Flask │ │ Node.js │ │ Grafana │ │ n8n │ ... 60+ │
│ │ .yaml │ │ .yaml │ │ .yaml │ │ .yaml │ │ .yaml │ │
│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │
│ │ │ │ │ │ │
└────────┼────────────┼────────────┼────────────┼────────────┼───────────────────┘
Port Allocation
How ServerKit Finds Available Ports
ServerKit automatically scans the database, Docker, and system sockets to find the first available port (starting from 8000) for new applications, ensuring no conflicts occur during deployment.
Database Linking
How Apps Connect to Databases
ServerKit automates the creation of databases and users, then injects the credentials as environment variables (DB_HOST, DB_USER, etc.) directly into the application container, allowing for seamless connectivity.
Workflow Automation
ServerKit includes a node-based visual workflow builder for automating server tasks.
┌─────────────────────────────────────────────────────────────────────────────────┐
│ WORKFLOW BUILDER │
│ │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
│ │ TRIGGER │──────▶│ ACTION │──────▶│ CONDITION │──────▶│ NOTIFY │ │
│ │ (Git Push)│ │ (Build) │ │ (Success?)│ │ (Discord) │ │
│ └───────────┘ └───────────┘ └─────┬─────┘ └───────────┘ │
│ │ │
│ ▼ │
│ ┌───────────┐ │
│ │ ROLLBACK │ │
│ └───────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
- Nodes: Represent individual steps (Triggers, Actions, Logic, Notifications).
- Edges: Define the flow of execution.
- Engine: The
WorkflowServiceparses the JSON graph and executes steps sequentially or in parallel.
Environment Pipeline
Specifically designed for WordPress, the environment pipeline allows for professional staging/dev workflows.
┌──────────────┐ promotion ┌──────────────┐ promotion ┌──────────────┐
│ DEV │───────────▶│ STAGING │───────────▶│ PRODUCTION │
│ (Standalone) │ │ (Standalone) │ │ (Production) │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
│ │ │
└─────────── sync ──────────┴─────────── sync ──────────┘
- Promotion: Push code (Git) and Database from a lower environment to a higher one.
- Syncing: Pull the latest production database and media to dev/staging for testing.
- Sanitization: Automatically strip sensitive user data during sync.
File Paths
Where Everything Lives
/var/serverkit/ # ServerKit data root
├── apps/ # All deployed applications
├── backups/ # Database backups
└── ssl/ # SSL certificates
/etc/serverkit/ # ServerKit configuration
├── templates/ # Template library (YAML files)
└── config.yaml # Main config
Component Diagram
ServerKit follows a modern 3-tier architecture:
- Frontend: React-based dashboard served via Nginx.
- Backend: Flask REST API managing Docker, Nginx, and system services.
- Agent: Go-based remote agent for multi-server management.
Deployment constraint — single WebSocket worker. The agent gateway keeps all connected-agent state (the registry of live agents, socket↔server index, session tokens, and in-flight command queues) in-memory in one process. Run the panel with a single gevent-websocket worker. Scaling to multiple workers without a shared backplane (e.g. a Redis message queue) will silently misroute or drop commands for agents connected to a different worker.
Troubleshooting
Refer to the Deployment Guide for detailed troubleshooting steps regarding 502 errors, container failures, and networking issues.