ServerKit/CONTRIBUTING.md

Contributing to ServerKit

Thank you for your interest in contributing to ServerKit! This guide will help you get started.

---

Table of Contents

• Code of Conduct
• Getting Started
• Development Setup
• Project Structure
• Making Changes
• Coding Standards
• Testing
• Submitting Changes
• Priority Areas

---

Code of Conduct

• Be respectful and inclusive
• Provide constructive feedback
• Focus on the issue, not the person
• Help others learn and grow

---

Getting Started

Prerequisites

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

Fork and Clone

# Fork the repository on GitHub, then:
git clone https://github.com/YOUR_USERNAME/ServerKit.git
cd ServerKit
git remote add upstream https://github.com/jhd3197/ServerKit.git

---

Development Setup

Backend Setup

# Create virtual environment
cd backend
python -m venv venv

# Activate virtual environment
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt  # Development dependencies

# Copy environment file
cp ../.env.example .env
# Edit .env with your settings

# Run development server
python run.py

The backend will be available at http://localhost:5000.

Frontend Setup

# In a new terminal
cd frontend

# Install dependencies
npm install

# Run development server
npm run dev

The frontend will be available at http://localhost:5173 with hot-reload.

Running Both Together

For development, run both the backend and frontend servers:

# Terminal 1 - Backend
cd backend && python run.py

# Terminal 2 - Frontend
cd frontend && npm run dev

Or use Docker:

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

---

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/        # LESS 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/ - LESS 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 LESS 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} />;
};

LESS/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: @card-bg;
  border-radius: @border-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 test
npm run test:coverage  # With coverage

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/main
   

2. Push your branch:

   git push origin feature/your-feature
   

3. Create Pull Request:

   • Go to GitHub and create a PR
   • Fill out the PR template
   • Link any related issues

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!