ServerKit/docs/LOCAL_DEVELOPMENT.md

Local Development Setup for Windows

This guide explains how to run ServerKit locally on Windows for development and testing.

Production Server Specs (Reference)

ServerKit is tested on Digital Ocean with these specs:

Spec	Value
OS	Ubuntu 24.04.3 LTS
CPU	2 cores (AMD)
RAM	4 GB
Disk	25 GB
Plan	Basic Droplet (~$12/mo)

For local development, similar or lower specs work fine.

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

# 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

# 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

# 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)

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)

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:

# 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

docker compose -f docker-compose.dev.yml up --build

---

Option 3: VS Code Dev Container

Add this to .devcontainer/devcontainer.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:

   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

# Find what's using the port
sudo lsof -i :5000
# Kill it
sudo kill -9 <PID>

Permission denied for Docker

sudo usermod -aG docker $USER
# Log out and back in

Database locked

# Remove the lock file
rm backend/instance/serverkit.db-journal

---

Exposing Your Local Control Plane (ngrok)

When developing locally on Windows/WSL you may want a remote ServerKit agent (or a Docker host on another machine) to connect back to your machine. The dev.sh and dev.ps1 scripts include a tunnel mode that starts the backend, frontend, and an ngrok tunnel pointed at the backend (port 5000).

Prerequisites

1. Install ngrok and authenticate once:

   # macOS / Linux / WSL
   brew install ngrok/ngrok/ngrok    # or: snap install ngrok
   ngrok config add-authtoken <YOUR_TOKEN>
   

   # Windows
   choco install ngrok               # or: scoop install ngrok
   ngrok config add-authtoken <YOUR_TOKEN>
   

2. (Optional) Reserve a domain in the ngrok dashboard so the URL stays stable across restarts.

Start with a tunnel

# Linux / macOS / WSL
./dev.sh tunnel

# Windows
.\dev.ps1 tunnel

The public ngrok URL is printed in green once the tunnel is up. Use it as the --server argument when registering an agent:

serverkit-agent register \
  --token "sk_reg_xxx" \
  --server "https://<your-tunnel>.ngrok-free.app"

Optional environment variables

Variable	Purpose
NGROK_DOMAIN	Use a reserved ngrok domain (e.g. my-app.ngrok-free.app).
NGROK_AUTHTOKEN	Override the authtoken (otherwise the one stored by ngrok config is used).
CORS_ORIGINS	Override CORS allow-list. The script defaults include https://*.ngrok-free.app, https://*.ngrok.app, https://*.ngrok.io.

---

Quick Start with WSL2 (Helper Script)

If you're on Windows and using WSL2 Ubuntu/Debian, you can skip the manual steps above and use the bundled setup helper:

# from inside WSL, in the cloned repo
bash scripts/setup-wsl.sh           # full setup
bash scripts/setup-wsl.sh --check   # dry-run / diagnostics only

The script will:

• Detect WSL and warn if the repo lives under /mnt/c (slow file I/O for hot-reload).
• Verify Ubuntu/Debian and install missing apt packages (python3, python3-venv, python3-pip, nodejs, npm, git, curl).
• Create backend/venv and install Python requirements.
• Run npm install in frontend/.
• Copy backend/.env.example to backend/.env if missing.
• Print WSL-specific tips (localhost forwarding, polling reloader, ngrok).

Once it finishes:

./dev.sh           # start backend + frontend
./dev.sh tunnel    # also expose backend via ngrok (see section above)