Skip to content

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

Add local development setup for Windows/WSL

Juan Denis1c0dbe923c79
diff --git a/dev-setup.sh b/dev-setup.sh
new file mode 100644
index 00000000..e028edbe
--- /dev/null
+++ b/dev-setup.sh
@@ -0,0 +1,90 @@
+#!/bin/bash
+#
+# ServerKit Local Development Setup for WSL/Linux
+# Usage: ./dev-setup.sh
+#
+
+set -e
+
+# Colors
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+echo -e "${BLUE}"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo " ServerKit Development Setup"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo -e "${NC}"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$SCRIPT_DIR"
+
+# Check if Python is installed
+if ! command -v python3 &> /dev/null; then
+ echo -e "${YELLOW}Installing Python...${NC}"
+ sudo apt update
+ sudo apt install -y python3 python3-pip python3-venv python3-dev
+fi
+
+# Check if Node is installed
+if ! command -v node &> /dev/null; then
+ echo -e "${YELLOW}Installing Node.js...${NC}"
+ curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+ sudo apt install -y nodejs
+fi
+
+# Create virtual environment
+if [ ! -d "venv" ]; then
+ echo -e "${BLUE}→ Creating Python virtual environment...${NC}"
+ python3 -m venv venv
+fi
+
+# Activate and install dependencies
+echo -e "${BLUE}→ Installing Python dependencies...${NC}"
+source venv/bin/activate
+pip install --quiet --upgrade pip
+pip install --quiet -r backend/requirements.txt
+pip install --quiet gunicorn gevent gevent-websocket
+
+# Install frontend dependencies
+echo -e "${BLUE}→ Installing frontend dependencies...${NC}"
+cd frontend
+npm install --silent
+cd ..
+
+# Create .env if not exists
+if [ ! -f ".env" ]; then
+ echo -e "${BLUE}→ Creating .env file...${NC}"
+ cat > .env << 'EOF'
+# Development Configuration
+SECRET_KEY=dev-secret-key-change-in-production
+JWT_SECRET_KEY=dev-jwt-key-change-in-production
+DATABASE_URL=sqlite:///backend/instance/serverkit.db
+CORS_ORIGINS=http://localhost,http://localhost:3000,http://localhost:5173
+FLASK_ENV=development
+EOF
+fi
+
+# Create instance directory
+mkdir -p backend/instance
+
+echo ""
+echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo -e "${GREEN} Setup Complete!${NC}"
+echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo ""
+echo "To start development:"
+echo ""
+echo " Terminal 1 (Backend):"
+echo " source venv/bin/activate"
+echo " cd backend && python run.py"
+echo ""
+echo " Terminal 2 (Frontend):"
+echo " cd frontend && npm run dev"
+echo ""
+echo "Access:"
+echo " Frontend: http://localhost:5173"
+echo " Backend: http://localhost:5000"
+echo ""
diff --git a/dev.bat b/dev.bat
new file mode 100644
index 00000000..a2a8d9f5
--- /dev/null
+++ b/dev.bat
@@ -0,0 +1,65 @@
+@echo off
+REM ServerKit Local Development Helper for Windows
+REM Usage: dev.bat [command]
+
+if "%1"=="" goto help
+if "%1"=="up" goto up
+if "%1"=="down" goto down
+if "%1"=="logs" goto logs
+if "%1"=="shell" goto shell
+if "%1"=="reset" goto reset
+if "%1"=="help" goto help
+goto help
+
+:up
+echo Starting ServerKit development environment...
+docker compose -f docker-compose.dev.yml up --build -d
+echo.
+echo ServerKit is starting up:
+echo Frontend: http://localhost:3000
+echo Backend: http://localhost:5000
+echo.
+echo Run 'dev.bat logs' to see logs
+goto end
+
+:down
+echo Stopping ServerKit development environment...
+docker compose -f docker-compose.dev.yml down
+goto end
+
+:logs
+docker compose -f docker-compose.dev.yml logs -f
+goto end
+
+:shell
+echo Opening shell in backend container...
+docker exec -it serverkit-backend-dev /bin/bash
+goto end
+
+:reset
+echo Resetting development environment (removing volumes)...
+docker compose -f docker-compose.dev.yml down -v
+echo Done. Run 'dev.bat up' to start fresh.
+goto end
+
+:help
+echo.
+echo ServerKit Development Helper
+echo ============================
+echo.
+echo Usage: dev.bat [command]
+echo.
+echo Commands:
+echo up Start development environment
+echo down Stop development environment
+echo logs View logs (Ctrl+C to exit)
+echo shell Open bash shell in backend container
+echo reset Stop and remove all data (fresh start)
+echo help Show this help message
+echo.
+echo Note: System management features (PHP, firewall, etc.)
+echo won't work in Docker mode. Use WSL for full testing.
+echo.
+goto end
+
+:end
diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml
new file mode 100644
index 00000000..8e809dde
--- /dev/null
+++ b/docker-compose.dev.yml
@@ -0,0 +1,69 @@
+# ==============================================
+# ServerKit Development Docker Compose
+# ==============================================
+# FOR LOCAL TESTING ONLY - System management features
+# (PHP install, firewall, etc.) won't work in Docker.
+#
+# Usage:
+# docker compose -f docker-compose.dev.yml up --build
+#
+# Access:
+# Frontend: http://localhost:3000
+# Backend: http://localhost:5000
+# ==============================================
+
+services:
+ backend:
+ build:
+ context: ./backend
+ dockerfile: Dockerfile
+ container_name: serverkit-backend-dev
+ environment:
+ - FLASK_ENV=development
+ - SECRET_KEY=dev-secret-key-not-for-production
+ - JWT_SECRET_KEY=dev-jwt-key-not-for-production
+ - DATABASE_URL=sqlite:////app/instance/serverkit.db
+ - CORS_ORIGINS=http://localhost,http://localhost:3000,http://localhost:5173
+ ports:
+ - "5000:5000"
+ volumes:
+ - dev-data:/app/instance
+ - dev-config:/etc/serverkit
+ networks:
+ - serverkit-dev
+ healthcheck:
+ test: ["CMD", "curl", "-f", "http://localhost:5000/api/v1/system/health"]
+ interval: 10s
+ timeout: 5s
+ retries: 3
+
+ frontend-dev:
+ image: node:20-alpine
+ container_name: serverkit-frontend-dev
+ working_dir: /app
+ command: sh -c "npm install && npm run dev -- --host 0.0.0.0 --port 3000"
+ environment:
+ - VITE_API_URL=http://localhost:5000
+ ports:
+ - "3000:3000"
+ volumes:
+ - ./frontend:/app
+ - frontend-modules:/app/node_modules
+ depends_on:
+ backend:
+ condition: service_healthy
+ networks:
+ - serverkit-dev
+
+networks:
+ serverkit-dev:
+ driver: bridge
+ name: serverkit-dev
+
+volumes:
+ dev-data:
+ name: serverkit-dev-data
+ dev-config:
+ name: serverkit-dev-config
+ frontend-modules:
+ name: serverkit-frontend-modules
diff --git a/docs/LOCAL_DEVELOPMENT.md b/docs/LOCAL_DEVELOPMENT.md
new file mode 100644
index 00000000..e25c86e0
--- /dev/null
+++ b/docs/LOCAL_DEVELOPMENT.md
@@ -0,0 +1,240 @@
+# Local Development Setup for Windows
+
+This guide explains how to run ServerKit locally on Windows for development and testing.
+
+## Prerequisites
+
+- **Windows 10/11** with WSL2 enabled
+- **Docker Desktop** for Windows (with WSL2 backend)
+- **Git** for Windows
+
+## Option 1: Full Local Development (Recommended)
+
+This mimics the production setup where backend runs on host and frontend in Docker.
+
+### Step 1: Install WSL2 + Ubuntu
+
+```powershell
+# Run in PowerShell as Administrator
+wsl --install -d Ubuntu-24.04
+```
+
+Restart your computer, then open Ubuntu from Start menu to complete setup.
+
+### Step 2: Install Dependencies in WSL
+
+```bash
+# Update packages
+sudo apt update && sudo apt upgrade -y
+
+# Install Python
+sudo apt install -y python3 python3-pip python3-venv python3-dev
+
+# Install build tools
+sudo apt install -y build-essential libffi-dev libssl-dev
+
+# Install iproute2 (for ss command)
+sudo apt install -y iproute2
+
+# Install Docker (inside WSL)
+curl -fsSL https://get.docker.com | sh
+sudo usermod -aG docker $USER
+
+# Log out and back in for docker group to take effect
+```
+
+### Step 3: Clone and Setup
+
+```bash
+# Clone the repo (or navigate to your mounted Windows folder)
+cd ~
+git clone https://github.com/jhd3197/ServerKit.git
+cd ServerKit
+
+# Create virtual environment
+python3 -m venv venv
+source venv/bin/activate
+
+# Install dependencies
+pip install -r backend/requirements.txt
+pip install gunicorn gevent gevent-websocket
+
+# Create .env file
+cat > .env << 'EOF'
+SECRET_KEY=dev-secret-key-change-in-production
+JWT_SECRET_KEY=dev-jwt-key-change-in-production
+DATABASE_URL=sqlite:///backend/instance/serverkit.db
+CORS_ORIGINS=http://localhost,http://localhost:3000,http://localhost:5173
+FLASK_ENV=development
+EOF
+
+# Create instance directory
+mkdir -p backend/instance
+```
+
+### Step 4: Run Backend (Terminal 1)
+
+```bash
+cd ~/ServerKit
+source venv/bin/activate
+cd backend
+export $(cat ../.env | xargs)
+python run.py
+```
+
+Backend will be available at: `http://localhost:5000`
+
+### Step 5: Run Frontend (Terminal 2)
+
+```bash
+cd ~/ServerKit/frontend
+npm install
+npm run dev
+```
+
+Frontend will be available at: `http://localhost:5173`
+
+---
+
+## Option 2: Docker Compose (Simpler, but no host system access)
+
+Use this for quick UI testing. Note: System management features (PHP install, firewall, etc.) won't work.
+
+### docker-compose.dev.yml
+
+Create this file in the project root:
+
+```yaml
+# Development docker-compose - FOR TESTING UI ONLY
+# System management features won't work in this mode
+
+services:
+ backend:
+ build:
+ context: ./backend
+ dockerfile: Dockerfile
+ container_name: serverkit-backend-dev
+ environment:
+ - FLASK_ENV=development
+ - SECRET_KEY=dev-secret-key
+ - JWT_SECRET_KEY=dev-jwt-key
+ - DATABASE_URL=sqlite:////app/instance/serverkit.db
+ - CORS_ORIGINS=http://localhost,http://localhost:3000
+ ports:
+ - "5000:5000"
+ volumes:
+ - ./backend:/app
+ - dev-data:/app/instance
+ networks:
+ - serverkit-dev
+
+ frontend:
+ build:
+ context: ./frontend
+ dockerfile: Dockerfile.dev
+ container_name: serverkit-frontend-dev
+ environment:
+ - VITE_API_URL=http://localhost:5000
+ ports:
+ - "3000:3000"
+ volumes:
+ - ./frontend:/app
+ - /app/node_modules
+ depends_on:
+ - backend
+ networks:
+ - serverkit-dev
+
+networks:
+ serverkit-dev:
+ driver: bridge
+
+volumes:
+ dev-data:
+```
+
+### Run with Docker Compose
+
+```bash
+docker compose -f docker-compose.dev.yml up --build
+```
+
+---
+
+## Option 3: VS Code Dev Container
+
+Add this to `.devcontainer/devcontainer.json`:
+
+```json
+{
+ "name": "ServerKit Dev",
+ "dockerComposeFile": "../docker-compose.dev.yml",
+ "service": "backend",
+ "workspaceFolder": "/app",
+ "customizations": {
+ "vscode": {
+ "extensions": [
+ "ms-python.python",
+ "ms-python.vscode-pylance",
+ "dbaeumer.vscode-eslint"
+ ]
+ }
+ },
+ "forwardPorts": [5000, 3000],
+ "postCreateCommand": "pip install -r requirements.txt"
+}
+```
+
+---
+
+## Quick Reference
+
+| Component | Production (DO Server) | Local Dev (WSL) |
+|-----------|----------------------|-----------------|
+| Backend | systemd service | `python run.py` |
+| Frontend | Docker + nginx | `npm run dev` |
+| Database | SQLite in /opt/serverkit | SQLite in ./backend/instance |
+| System Access | Full (sudo, systemctl) | Full (in WSL) |
+
+## Testing System Features
+
+To test PHP installation, firewall, etc. locally:
+
+1. Use **Option 1** (WSL) - this gives you a real Linux environment
+2. Install the same packages as production:
+ ```bash
+ sudo apt install -y firewalld vsftpd
+ ```
+3. The backend will have real system access
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SECRET_KEY` | Flask secret key | Required |
+| `JWT_SECRET_KEY` | JWT signing key | Required |
+| `DATABASE_URL` | SQLite path | `sqlite:///serverkit.db` |
+| `CORS_ORIGINS` | Allowed origins | `http://localhost` |
+| `FLASK_ENV` | development/production | `production` |
+
+## Troubleshooting
+
+### Port already in use
+```bash
+# Find what's using the port
+sudo lsof -i :5000
+# Kill it
+sudo kill -9 <PID>
+```
+
+### Permission denied for Docker
+```bash
+sudo usermod -aG docker $USER
+# Log out and back in
+```
+
+### Database locked
+```bash
+# Remove the lock file
+rm backend/instance/serverkit.db-journal
+```