Skip to content

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

Revamp README and add architecture documentation

Juan Denis26da2c65e873
diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml
new file mode 100644
index 00000000..56460712
--- /dev/null
+++ b/.github/FUNDING.yml
@@ -0,0 +1,15 @@
+# These are supported funding model platforms
+
+github: [jhd3197]
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+polar: # Replace with a single Polar username
+buy_me_a_coffee: jhd3197
+thanks_dev: # Replace with a single thanks.dev username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']
\ No newline at end of file
diff --git a/README.md b/README.md
index 154a91bf..954e50bb 100644
--- a/README.md
+++ b/README.md
@@ -1,20 +1,30 @@
+<div align="center">
+
# ServerKit
-<p align="center">
- <img width="700" alt="server-kit" src="https://github.com/user-attachments/assets/bfc59e75-8f90-4674-a222-e18213b628b7" />
-</p>
+<img width="700" alt="server-kit" src="https://github.com/user-attachments/assets/bfc59e75-8f90-4674-a222-e18213b628b7" />
-<p align="center">
- <strong>Modern, self-hosted server management panel</strong><br>
- An open-source alternative to ServerPilot, RunCloud, and Coolify
-</p>
+**Self-hosted infrastructure, made simple**
-<p align="center">
- <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License">
- <img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python">
- <img src="https://img.shields.io/badge/react-18-blue.svg" alt="React">
- <img src="https://img.shields.io/badge/docker-ready-blue.svg" alt="Docker">
-</p>
+<br>
+
+[![License](https://img.shields.io/badge/license-MIT-blue.svg?style=for-the-badge)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.11+-3776AB.svg?style=for-the-badge&logo=python&logoColor=white)](https://python.org)
+[![React](https://img.shields.io/badge/react-18-61DAFB.svg?style=for-the-badge&logo=react&logoColor=black)](https://reactjs.org)
+[![Docker](https://img.shields.io/badge/docker-ready-2496ED.svg?style=for-the-badge&logo=docker&logoColor=white)](https://docker.com)
+
+[![Flask](https://img.shields.io/badge/flask-3.0-000000.svg?style=flat-square&logo=flask&logoColor=white)](https://flask.palletsprojects.com)
+[![Nginx](https://img.shields.io/badge/nginx-reverse_proxy-009639.svg?style=flat-square&logo=nginx&logoColor=white)](https://nginx.org)
+[![Let's Encrypt](https://img.shields.io/badge/SSL-Let's_Encrypt-003A70.svg?style=flat-square&logo=letsencrypt&logoColor=white)](https://letsencrypt.org)
+[![MySQL](https://img.shields.io/badge/mysql-8.0-4479A1.svg?style=flat-square&logo=mysql&logoColor=white)](https://mysql.com)
+[![PostgreSQL](https://img.shields.io/badge/postgresql-15-4169E1.svg?style=flat-square&logo=postgresql&logoColor=white)](https://postgresql.org)
+[![Ubuntu](https://img.shields.io/badge/ubuntu-22.04+-E95420.svg?style=flat-square&logo=ubuntu&logoColor=white)](https://ubuntu.com)
+
+<br>
+
+[Features](#features) · [Quick Start](#quick-start) · [Documentation](#documentation) · [Architecture](docs/ARCHITECTURE.md) · [Contributing](#contributing)
+
+</div>
---
@@ -26,6 +36,55 @@ ServerKit is a lightweight, modern server control panel for managing web applica
---
+## Architecture
+
+<details>
+<summary><strong>View How It Works</strong></summary>
+
+<br>
+
+```
+ ┌──────────────────┐
+ │ INTERNET │
+ └────────┬─────────┘
+ │
+ ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│ YOUR SERVER │
+│ │
+│ ┌─────────────────────────────────────────────────────────────────────┐ │
+│ │ NGINX (Reverse Proxy) │ │
+│ │ :80 / :443 │ │
+│ │ │ │
+│ │ app1.com ──┐ app2.com ──┐ api.app3.com ──┐ │ │
+│ └───────────────┼─────────────────┼─────────────────────┼─────────────┘ │
+│ │ proxy_pass │ proxy_pass │ proxy_pass │
+│ ▼ ▼ ▼ │
+│ ┌─────────────────────────────────────────────────────────────────────┐ │
+│ │ DOCKER CONTAINERS │ │
+│ │ │ │
+│ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ │
+│ │ │ WordPress │ │ Flask │ │ Node.js │ ... │ │
+│ │ │ :8001 │ │ :8002 │ │ :8003 │ │ │
+│ │ └─────┬─────┘ └───────────┘ └───────────┘ │ │
+│ └──────────┼──────────────────────────────────────────────────────────┘ │
+│ │ │
+│ ▼ │
+│ ┌─────────────────────────────────────────────────────────────────────┐ │
+│ │ DATABASES │ │
+│ │ MySQL :3306 PostgreSQL :5432 Redis :6379 │ │
+│ └─────────────────────────────────────────────────────────────────────┘ │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+</details>
+
+**[View Full Architecture Documentation →](docs/ARCHITECTURE.md)**
+
+> Includes: Request flow diagrams, template system, port allocation, database linking, and troubleshooting guides.
+
+---
+
## Features
### Application Management
@@ -82,7 +141,15 @@ ServerKit is a lightweight, modern server control panel for managing web applica
## Quick Start
-### Option 1: Docker (Recommended)
+### Option 1: One-Line Install (Recommended)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/jhd3197/serverkit/main/install.sh | bash
+```
+
+> Works on Ubuntu 22.04+ and Debian 12+. Sets up everything automatically.
+
+### Option 2: Docker
```bash
# Clone the repository
@@ -99,12 +166,6 @@ docker compose up -d
# Access at http://localhost
```
-### Option 2: One-Line Install (Ubuntu)
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/jhd3197/serverkit/main/install.sh | bash
-```
-
### Option 3: Manual Installation
See [Installation Guide](docs/INSTALLATION.md) for detailed instructions.
@@ -140,6 +201,7 @@ See [Installation Guide](docs/INSTALLATION.md) for detailed instructions.
| Document | Description |
|----------|-------------|
+| [Architecture](docs/ARCHITECTURE.md) | System design, request flow, and diagrams |
| [Installation Guide](docs/INSTALLATION.md) | Complete setup instructions |
| [Deployment Guide](docs/DEPLOYMENT.md) | CLI commands and production deployment |
| [API Reference](docs/API.md) | REST API documentation |
@@ -308,44 +370,15 @@ Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
----
-
-## Roadmap
-
-See [ROADMAP.md](ROADMAP.md) for the full development plan.
-
-**Recent additions:**
-- Two-Factor Authentication (2FA)
-- Discord/Slack/Telegram notifications
-- ClamAV malware scanning
-- File integrity monitoring
-- Environment variable management
-- Cron job management
-
-**Coming soon:**
-- Multi-server management
-- Git deployment with webhooks
-- Let's Encrypt wildcard SSL
-- Email server management
-- Backup to S3/B2
-
----
-
-## License
-
-This project is licensed under the MIT License - see [LICENSE](LICENSE) for details.
-
----
-
-## Acknowledgments
-
-- Inspired by [Coolify](https://coolify.io), [ServerPilot](https://serverpilot.io), and [RunCloud](https://runcloud.io)
-- UI inspired by modern admin dashboards
---
<p align="center">
- <strong>ServerKit</strong> - Simple. Modern. Self-hosted.<br>
+ <strong>ServerKit</strong> — Simple. Modern. Self-hosted.<br>
<a href="https://github.com/jhd3197/ServerKit/issues">Report Bug</a> ·
<a href="https://github.com/jhd3197/ServerKit/issues">Request Feature</a>
</p>
+
+<p align="center">
+ Made with ❤️ by <a href="https://juandenis.com">Juan Denis</a>
+</p>
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
new file mode 100644
index 00000000..9b2aad3a
--- /dev/null
+++ b/docs/ARCHITECTURE.md
@@ -0,0 +1,560 @@
+# ServerKit Architecture
+
+> Deep dive into how ServerKit connects domains, apps, containers, and databases.
+
+---
+
+## Table of Contents
+
+- [System Overview](#system-overview)
+- [Request Flow](#request-flow)
+- [Template System](#template-system)
+- [Port Allocation](#port-allocation)
+- [Database Linking](#database-linking)
+- [File Paths](#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
+└─────────┘
+```
+
+### Detailed Nginx → Container Flow
+
+```
+ NGINX CONFIG DOCKER
+ /etc/nginx/sites-enabled/ CONTAINER
+ ───────────────────────── ─────────────────
+
+ server {
+ listen 80;
+ server_name my-blog.com;
+ ┌─────────────────┐
+ location / { │ WordPress │
+ proxy_pass ─────────────────────────► │ │
+ http://127.0.0.1:8001; │ 0.0.0.0:80 │
+ proxy_set_header Host $host; │ ▲ │
+ proxy_set_header X-Real-IP ...; │ │ │
+ } │ (mapped to │
+ } │ host:8001) │
+ └─────────────────┘
+```
+
+---
+
+## Template System
+
+### Template → App → Domain Lifecycle
+
+```
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│ TEMPLATE LIBRARY │
+│ /etc/serverkit/templates/ │
+│ │
+│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
+│ │WordPress│ │ Flask │ │ Node.js │ │ Grafana │ │ n8n │ ... 60+ │
+│ │ .yaml │ │ .yaml │ │ .yaml │ │ .yaml │ │ .yaml │ │
+│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │
+│ │ │ │ │ │ │
+└────────┼────────────┼────────────┼────────────┼────────────┼───────────────────┘
+ │ │ │ │ │
+ │ User clicks "Deploy" in UI │
+ │ │ │
+ ▼ ▼ ▼
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│ SERVERKIT BACKEND │
+│ │
+│ TemplateService.install_template() │
+│ ├── 1. Parse template YAML │
+│ ├── 2. Generate unique port (8000-60000) │
+│ ├── 3. Substitute variables: │
+│ │ ${APP_NAME} → "my-blog" │
+│ │ ${HTTP_PORT} → "8247" │
+│ │ ${DB_PASSWORD} → "auto_generated" │
+│ ├── 4. Create /var/serverkit/apps/my-blog/docker-compose.yml │
+│ ├── 5. Run: docker compose up -d --build │
+│ └── 6. Store app record in database │
+│ │
+└─────────────────────────────────────────────────────────────────────────────────┘
+ │
+ ▼
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│ APP CREATED │
+│ │
+│ ┌─────────────────────────────────────────────────────────────────────────┐ │
+│ │ App Name: my-blog │ │
+│ │ Type: docker │ │
+│ │ Port: 8247 (auto-assigned) │ │
+│ │ Status: running │ │
+│ │ Container: my-blog │ │
+│ │ Path: /var/serverkit/apps/my-blog/ │ │
+│ │ │ │
+│ │ Private URL: http://server-ip:8247 ◄── Works immediately! │ │
+│ └─────────────────────────────────────────────────────────────────────────┘ │
+│ │
+└─────────────────────────────────────────────────────────────────────────────────┘
+ │
+ │ User clicks "Connect Domain"
+ ▼
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│ DOMAIN CONNECTED │
+│ │
+│ DomainService.create_domain() │
+│ ├── 1. Validate domain DNS points to server │
+│ ├── 2. Check container port is accessible │
+│ ├── 3. Generate Nginx config: │
+│ │ │
+│ │ server { │
+│ │ listen 80; │
+│ │ server_name my-blog.com; │
+│ │ │
+│ │ location / { │
+│ │ proxy_pass http://127.0.0.1:8247; ◄── Container port │
+│ │ proxy_set_header Host $host; │
+│ │ proxy_set_header X-Real-IP $remote_addr; │
+│ │ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; │
+│ │ proxy_set_header X-Forwarded-Proto $scheme; │
+│ │ } │
+│ │ } │
+│ │ │
+│ ├── 4. Write to /etc/nginx/sites-available/my-blog │
+│ ├── 5. Symlink to /etc/nginx/sites-enabled/my-blog │
+│ ├── 6. Test config: nginx -t │
+│ ├── 7. Reload: systemctl reload nginx │
+│ └── 8. (Optional) Request SSL via Let's Encrypt │
+│ │
+│ Public URL: https://my-blog.com ◄── Now accessible worldwide! │
+│ │
+└─────────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Template YAML Structure
+
+```yaml
+# Example: flask-hello-world.yaml
+
+id: flask-hello-world
+name: Flask - Hello World
+version: "1.0"
+description: Simple Flask debug app
+categories:
+ - development
+ - api
+
+variables:
+ - name: HTTP_PORT # Variable name
+ type: port # Auto-generates available port
+ default: "5000" # Starting port to search from
+ hidden: true # Don't show in UI
+
+compose: # Docker Compose configuration
+ services:
+ app:
+ image: python:3.12-slim
+ container_name: ${APP_NAME}
+ ports:
+ - "${HTTP_PORT}:5000" # Host:Container port mapping
+ environment:
+ - APP_NAME=${APP_NAME}
+ - EXTERNAL_PORT=${HTTP_PORT}
+```
+
+---
+
+## Port Allocation
+
+### How ServerKit Finds Available Ports
+
+```
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│ PORT ALLOCATION │
+│ │
+│ TemplateService._find_available_port(start=8000) │
+│ │
+│ ┌─────────────────────────────────────────────────────────────────────────┐ │
+│ │ Step 1: Check Database │ │
+│ │ SELECT port FROM applications WHERE port IS NOT NULL │ │
+│ │ Result: [8001, 8002, 8005, 8010] │ │
+│ └─────────────────────────────────────────────────────────────────────────┘ │
+│ │ │
+│ ▼ │
+│ ┌─────────────────────────────────────────────────────────────────────────┐ │
+│ │ Step 2: Check Docker │ │
+│ │ docker ps --format '{{.Ports}}' │ │
+│ │ Parse: "0.0.0.0:8003->80/tcp" → 8003 │ │
+│ │ Result: [8003, 8004] │ │
+│ └─────────────────────────────────────────────────────────────────────────┘ │
+│ │ │
+│ ▼ │
+│ ┌─────────────────────────────────────────────────────────────────────────┐ │
+│ │ Step 3: Socket Bind Test │ │
+│ │ Try: socket.bind(('127.0.0.1', port)) │ │
+│ │ If fails → port in use by system │ │
+│ └─────────────────────────────────────────────────────────────────────────┘ │
+│ │ │
+│ ▼ │
+│ ┌─────────────────────────────────────────────────────────────────────────┐ │
+│ │ Step 4: Return First Available │ │
+│ │ │ │
+│ │ Checking 8000... taken (DB) │ │
+│ │ Checking 8001... taken (DB) │ │
+│ │ Checking 8002... taken (DB) │ │
+│ │ Checking 8003... taken (Docker) │ │
+│ │ Checking 8004... taken (Docker) │ │
+│ │ Checking 8005... taken (DB) │ │
+│ │ Checking 8006... AVAILABLE ✓ │ │
+│ │ │ │
+│ │ Return: 8006 │ │
+│ └─────────────────────────────────────────────────────────────────────────┘ │
+│ │
+└─────────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Port Map Example
+
+```
+┌──────────┬────────────────────────────────────────┐
+│ Port │ Service │
+├──────────┼────────────────────────────────────────┤
+│ 22 │ SSH │
+│ 80 │ Nginx (HTTP) │
+│ 443 │ Nginx (HTTPS) │
+│ 3306 │ MySQL │
+│ 5432 │ PostgreSQL │
+│ 5000 │ ServerKit Backend API │
+│ 6379 │ Redis │
+├──────────┼────────────────────────────────────────┤
+│ 8001 │ App: wordpress-blog │
+│ 8002 │ App: flask-api │
+│ 8003 │ App: node-frontend │
+│ 8004 │ App: grafana-monitoring │
+│ 8005 │ App: n8n-automation │
+│ 8006 │ App: (next available) │
+│ ... │ ... │
+│ 60000 │ (max port range) │
+└──────────┴────────────────────────────────────────┘
+```
+
+---
+
+## Database Linking
+
+### How Apps Connect to Databases
+
+```
+┌────────────────────────────────────────────────────────────────────────────────┐
+│ │
+│ ┌──────────────────┐ ┌──────────────────┐ │
+│ │ APP (Flask) │ │ DATABASE (MySQL) │ │
+│ │ │ │ │ │
+│ │ Needs DB access │ │ db: my_app_db │ │
+│ │ │ │ user: app_user │ │
+│ └────────┬─────────┘ └────────┬─────────┘ │
+│ │ │ │
+│ │ User clicks "Link Database" │ │
+│ │ │ │
+│ └──────────────┬───────────────────┘ │
+│ │ │
+│ ▼ │
+│ ┌────────────────────────────────────────────────────────────────────────┐ │
+│ │ SERVERKIT LINKS THEM │ │
+│ │ │ │
+│ │ 1. Creates database: my_app_db │ │
+│ │ 2. Creates user with secure password │ │
+│ │ 3. Grants permissions │ │
+│ │ 4. Injects environment variables into app container: │ │
+│ │ │ │
+│ │ ┌─────────────────────────────────────────────────────────────┐ │ │
+│ │ │ DB_HOST=localhost │ │ │
+│ │ │ DB_PORT=3306 │ │ │
+│ │ │ DB_NAME=my_app_db │ │ │
+│ │ │ DB_USER=app_user │ │ │
+│ │ │ DB_PASSWORD=xK9#mP2$vL7@nQ4 │ │ │
+│ │ │ │ │ │
+│ │ │ # Also provides connection URL format: │ │ │
+│ │ │ DATABASE_URL=mysql://app_user:xK9#mP2$vL7@nQ4@localhost/db │ │ │
+│ │ └─────────────────────────────────────────────────────────────┘ │ │
+│ │ │ │
+│ │ 5. Restarts app container to pick up new env vars │ │
+│ │ │ │
+│ └────────────────────────────────────────────────────────────────────────┘ │
+│ │ │
+│ ▼ │
+│ ┌────────────────────────────────────────────────────────────────────────┐ │
+│ │ APP CODE │ │
+│ │ │ │
+│ │ # Python/Flask example │ │
+│ │ import os │ │
+│ │ import mysql.connector │ │
+│ │ │ │
+│ │ db = mysql.connector.connect( │ │
+│ │ host=os.environ['DB_HOST'], # localhost │ │
+│ │ port=os.environ['DB_PORT'], # 3306 │ │
+│ │ database=os.environ['DB_NAME'], # my_app_db │ │
+│ │ user=os.environ['DB_USER'], # app_user │ │
+│ │ password=os.environ['DB_PASSWORD'] │ │
+│ │ ) │ │
+│ │ │ │
+│ │ # Or use the URL directly: │ │
+│ │ # SQLAlchemy: create_engine(os.environ['DATABASE_URL']) │ │
+│ │ │ │
+│ └────────────────────────────────────────────────────────────────────────┘ │
+│ │
+└─────────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## File Paths
+
+### Where Everything Lives
+
+```
+SERVER FILESYSTEM
+─────────────────────────────────────────────────────────────────────────────────
+
+/var/serverkit/ # ServerKit data root
+├── apps/ # All deployed applications
+│ ├── my-blog/
+│ │ ├── docker-compose.yml # Generated from template
+│ │ ├── .env # Environment variables
+│ │ └── data/ # Persistent volumes
+│ ├── flask-api/
+│ │ ├── docker-compose.yml
+│ │ └── app/ # Application code
+│ └── ...
+│
+├── backups/ # Database backups
+│ ├── mysql/
+│ └── postgres/
+│
+└── ssl/ # SSL certificates (if not using certbot)
+
+/etc/serverkit/ # ServerKit configuration
+├── templates/ # Template library (YAML files)
+│ ├── wordpress.yaml
+│ ├── flask-hello-world.yaml
+│ ├── grafana.yaml
+│ └── ...
+└── config.yaml # Main config
+
+/etc/nginx/ # Nginx configuration
+├── sites-available/ # All site configs
+│ ├── my-blog # Generated by ServerKit
+│ ├── flask-api
+│ └── default
+├── sites-enabled/ # Enabled sites (symlinks)
+│ ├── my-blog -> ../sites-available/my-blog
+│ └── flask-api -> ../sites-available/flask-api
+└── nginx.conf # Main nginx config
+
+/var/log/nginx/ # Nginx logs (per-app)
+├── my-blog.access.log
+├── my-blog.error.log
+├── flask-api.access.log
+└── flask-api.error.log
+
+/var/lib/mysql/ # MySQL data
+/var/lib/postgresql/ # PostgreSQL data
+```
+
+---
+
+## Component Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│ SERVERKIT │
+│ │
+│ ┌─────────────────────────────────────────────────────────────────────────┐ │
+│ │ FRONTEND (React) │ │
+│ │ Served via Nginx :80/443 │ │
+│ │ │ │
+│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
+│ │ │Dashboard │ │ Apps │ │ Domains │ │ Docker │ │ Security │ │ │
+│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
+│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
+│ │ │Databases │ │Templates │ │ Firewall │ │ Cron │ │ Settings │ │ │
+│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
+│ │ │ │
+│ └─────────────────────────────────┬────────────────────────────────────────┘ │
+│ │ │
+│ REST API + WebSocket │
+│ │ │
+│ ▼ │
+│ ┌─────────────────────────────────────────────────────────────────────────┐ │
+│ │ BACKEND (Flask) │ │
+│ │ Port 5000 │ │
+│ │ │ │
+│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │
+│ │ │ SERVICES │ │ │
+│ │ │ │ │ │
+│ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │
+│ │ │ │DockerService │ │ NginxService │ │TemplateServ. │ │ │ │
+│ │ │ │ │ │ │ │ │ │ │ │
+│ │ │ │ • compose_up │ │ • create_site│ │ • install │ │ │ │
+│ │ │ │ • logs │ │ • enable_ssl │ │ • variables │ │ │ │
+│ │ │ │ • stats │ │ • reload │ │ • validate │ │ │ │
+│ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │
+│ │ │ │ │ │
+│ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │
+│ │ │ │ DBService │ │ SSLService │ │SecurityServ. │ │ │ │
+│ │ │ │ │ │ │ │ │ │ │ │
+│ │ │ │ • create_db │ │ • certbot │ │ • ClamAV │ │ │ │
+│ │ │ │ • users │ │ • renew │ │ • 2FA │ │ │ │
+│ │ │ │ • backup │ │ • wildcard │ │ • firewall │ │ │ │
+│ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │
+│ │ │ │ │ │
+│ │ └──────────────────────────────────────────────────────────────────┘ │ │
+│ │ │ │
+│ └─────────────────────────────────┬────────────────────────────────────────┘ │
+│ │ │
+│ ▼ │
+│ ┌─────────────────────────────────────────────────────────────────────────┐ │
+│ │ DATABASE (SQLite/PostgreSQL) │ │
+│ │ │ │
+│ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌─────────┐ │ │
+│ │ │ Apps │ │ Domains │ │ Users │ │ Databases │ │ Settings│ │ │
+│ │ └───────────┘ └───────────┘ └───────────┘ └───────────┘ └─────────┘ │ │
+│ │ │ │
+│ └─────────────────────────────────────────────────────────────────────────┘ │
+│ │
+└──────────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Troubleshooting
+
+### 502 Bad Gateway
+
+```
+Problem: Nginx can't reach the container
+
+Check:
+┌─────────────────────────────────────────────────────────────────┐
+│ 1. Is container running? │
+│ docker ps | grep <app-name> │
+│ │
+│ 2. Is port bound to host? │
+│ docker port <container-name> │
+│ Expected: 5000/tcp -> 0.0.0.0:8001 │
+│ │
+│ 3. Is port accessible? │
+│ curl -I http://127.0.0.1:8001 │
+│ Expected: HTTP/1.1 200 OK │
+│ │
+│ 4. Does nginx config have correct port? │
+│ cat /etc/nginx/sites-enabled/<app-name> │
+│ Check: proxy_pass http://127.0.0.1:8001; │
+│ │
+│ 5. Check nginx error log: │
+│ tail -50 /var/log/nginx/<app-name>.error.log │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Container Won't Start
+
+```
+Problem: docker compose up fails
+
+Check:
+┌─────────────────────────────────────────────────────────────────┐
+│ 1. Check compose logs: │
+│ cd /var/serverkit/apps/<app-name> │
+│ docker compose logs │
+│ │
+│ 2. Validate compose file: │
+│ docker compose config │
+│ │
+│ 3. Check for port conflicts: │
+│ docker ps --format "{{.Ports}}" │
+│ netstat -tulpn | grep <port> │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## See Also
+
+- [Installation Guide](INSTALLATION.md)
+- [API Reference](API.md)
+- [Deployment Guide](DEPLOYMENT.md)
diff --git a/frontend/dist/index.html b/frontend/dist/index.html
index 7b972305..9f6f3d5e 100644
--- a/frontend/dist/index.html
+++ b/frontend/dist/index.html
@@ -6,7 +6,7 @@
<link rel="icon" type="image/svg+xml" href="/vite.svg" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>React Dashboard Template</title>
- <script type="module" crossorigin src="/assets/index-wSLRVClq.js"></script>
+ <script type="module" crossorigin src="/assets/index-COkwSdPW.js"></script>
<link rel="stylesheet" crossorigin href="/assets/index-3nNiERFn.css">
</head>