ServerKit/CONTRIBUTING.md

Contributing to ServerKit

Quick Setup

Windows (WSL2) — Recommended

# 1. Install WSL (PowerShell as Admin)
wsl --install -d Ubuntu-22.04
# Restart, create user when prompted

# 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
./dev.sh

Open http://localhost:41921 — login: admin / admin

Troubleshooting: If you get bad interpreter error, fix line endings:

sed -i 's/\r$//' ./scripts/dev/*.sh

Linux / macOS

./scripts/dev/setup-linux.sh
./dev.sh

Docker

./scripts/dev/dev.bat up   # Windows
docker compose up -d --build  # Linux/Mac

The compose stack runs the all-in-one panel container (Dockerfile) on http://localhost:5000. It has no access to the host, so system-management features (packages, firewall, systemd, host nginx) are unavailable — use ./dev.sh for those.

---

Quick Reference

Task	Command
Start both	./dev.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

---

Manual Setup

Click to expand manual setup steps

Prerequisites

• Python 3.11+
• Node.js 20+
• Docker (optional)
• Git

Fork and Clone

git clone https://github.com/YOUR_USERNAME/ServerKit.git
cd ServerKit
git remote add upstream https://github.com/jhd3197/ServerKit.git
git checkout dev

Backend Setup

cd backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
python run.py

Frontend Setup

cd frontend
npm install
npm run dev

---

Project Structure

ServerKit/
├── backend/                 # Flask API
│   ├── app/
│   │   ├── api/            # API route blueprints
│   │   ├── models/         # SQLAlchemy models
│   │   └── services/       # Business logic
│   ├── config.py           # Configuration
│   ├── run.py              # Application entry point
│   └── requirements.txt
│
├── frontend/               # React application
│   ├── src/
│   │   ├── components/    # Reusable components
│   │   ├── pages/         # Page components
│   │   ├── services/      # API client
│   │   └── styles/        # SCSS stylesheets
│   ├── package.json
│   └── vite.config.js
│
├── docs/                   # Documentation
├── nginx/                  # Nginx configuration
└── docker-compose.yml

Key Files

Backend:

• backend/app/__init__.py - Flask app factory
• backend/app/api/ - API endpoints (one file per feature)
• backend/app/services/ - Business logic services
• backend/app/models/ - Database models

Frontend:

• frontend/src/App.jsx - Main app with routing
• frontend/src/pages/ - Page components
• frontend/src/components/ - Shared components
• frontend/src/services/api.js - API client
• frontend/src/styles/ - SCSS stylesheets

---

Making Changes

Branch Naming

Use descriptive branch names:

feature/multi-server-support
fix/login-redirect-loop
docs/api-examples
refactor/notification-service

Commit Messages

Write clear, concise commit messages:

Add Discord webhook notification support

- Create NotificationService for webhooks
- Add notification API endpoints
- Implement Discord embed formatting
- Add frontend notification settings

Format:

• First line: Brief summary (50 chars max)
• Blank line
• Body: Detailed description (wrap at 72 chars)

---

Coding Standards

Python (Backend)

• Follow PEP 8 style guide
• Use type hints where helpful
• Document public functions with docstrings
• Use meaningful variable names

def get_system_stats() -> dict:
    """
    Retrieve current system statistics.

    Returns:
        dict: CPU, memory, disk, and network stats
    """
    cpu_percent = psutil.cpu_percent(interval=1)
    memory = psutil.virtual_memory()
    # ...

JavaScript/React (Frontend)

• Use functional components with hooks
• Use meaningful component and variable names
• Keep components focused and small
• Use SCSS for styling (not inline styles)

const ServerStats = ({ serverId }) => {
  const [stats, setStats] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    fetchServerStats(serverId).then(setStats);
  }, [serverId]);

  if (loading) return <LoadingSpinner />;
  return <StatsDisplay stats={stats} />;
};

SCSS/CSS (Styles)

• Use the existing design system variables
• Follow BEM-like naming conventions
• Keep specificity low
• Use the component/page file structure

.notification-card {
  background: $bg-card;
  border-radius: $radius-md;

  &__header {
    padding: $spacing-md;
  }

  &--expanded {
    border-color: $primary-color;
  }
}

---

Testing

Backend Tests

cd backend
pytest
pytest --cov=app  # With coverage

Frontend Tests

cd frontend
npm run lint     # ESLint
npm run build    # Production build (compile check)

There is no frontend unit-test suite yet — linting and a clean production build are the current gate. See dev.ps1 validate / dev.sh validate below for the full pre-submit check.

Validate Before Submitting

Run the dev validation suite to check for common issues:

# Windows
.\dev.ps1 validate

# Linux/macOS
./dev.sh validate

This runs eslint, bandit (security scanner), pytest, and a frontend production build.

Manual Testing

Before submitting, test your changes:

1. Run the full application
2. Test the feature in multiple browsers
3. Test error cases and edge cases
4. Verify responsive design (mobile/tablet)

---

Submitting Changes

Pull Request Process

1. Update your fork:

   git fetch upstream
   git rebase upstream/dev
   

2. Push your branch:

   git push origin feature/your-feature
   

3. Create Pull Request:

   • Go to GitHub and create a PR targeting the dev branch (not main)
   • Fill out the PR template
   • Link any related issues

Important: All PRs should target the dev branch, not main. The main branch is reserved for stable releases.

4. PR Description:
   • Describe what changed and why
   • Include screenshots for UI changes
   • List testing steps
   • Note any breaking changes

PR Checklist

• Code follows project style guidelines
• Self-reviewed the code
• Added/updated tests if needed
• Updated documentation if needed
• No console errors or warnings
• Tested on multiple browsers (for frontend)

Review Process

1. Maintainers will review your PR
2. Address any requested changes
3. Once approved, your PR will be merged

---

Priority Areas

We especially welcome contributions in these areas:

High Priority

• Multi-Server Support - Agent development, remote monitoring
• Git Deployment - GitHub/GitLab webhooks, auto-deploy
• Backup System - S3/B2 integration, scheduled backups
• Security Enhancements - Fail2ban, SSH key management

Medium Priority

• Email Server - Postfix/Dovecot integration
• API Improvements - Rate limiting, API keys
• Team Features - Multi-user, RBAC

Always Welcome

• Bug fixes
• Documentation improvements
• Test coverage
• UI/UX improvements
• Performance optimizations
• Accessibility improvements

---

Questions?

• Open a GitHub Discussion
• Check existing Issues
• Review the Documentation

---

Thank you for contributing to ServerKit!