mirror of
https://github.com/jhd3197/ServerKit.git
synced 2026-11-08 21:14:47 +09:00
Juan Denis
83d7997b1a
Introduces a production-ready Dockerfile, a comprehensive CONTRIBUTING.md, and new documentation files (API, installation, roadmap). Updates .env.example with improved comments and structure, enhances .gitignore, and refines the README with expanded features, requirements, and setup instructions. Roadmap and planning files are reorganized, and obsolete HTML is removed.
367 lines
7.3 KiB
Markdown
367 lines
7.3 KiB
Markdown
# 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](#code-of-conduct)
|
|
- [Getting Started](#getting-started)
|
|
- [Development Setup](#development-setup)
|
|
- [Project Structure](#project-structure)
|
|
- [Making Changes](#making-changes)
|
|
- [Coding Standards](#coding-standards)
|
|
- [Testing](#testing)
|
|
- [Submitting Changes](#submitting-changes)
|
|
- [Priority Areas](#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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# Terminal 1 - Backend
|
|
cd backend && python run.py
|
|
|
|
# Terminal 2 - Frontend
|
|
cd frontend && npm run dev
|
|
```
|
|
|
|
Or use Docker:
|
|
|
|
```bash
|
|
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
|
|
|
|
```python
|
|
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)
|
|
|
|
```jsx
|
|
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
|
|
|
|
```less
|
|
.notification-card {
|
|
background: @card-bg;
|
|
border-radius: @border-radius-md;
|
|
|
|
&__header {
|
|
padding: @spacing-md;
|
|
}
|
|
|
|
&--expanded {
|
|
border-color: @primary-color;
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Testing
|
|
|
|
### Backend Tests
|
|
|
|
```bash
|
|
cd backend
|
|
pytest
|
|
pytest --cov=app # With coverage
|
|
```
|
|
|
|
### Frontend Tests
|
|
|
|
```bash
|
|
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:**
|
|
```bash
|
|
git fetch upstream
|
|
git rebase upstream/main
|
|
```
|
|
|
|
2. **Push your branch:**
|
|
```bash
|
|
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](https://github.com/jhd3197/ServerKit/discussions)
|
|
- Check existing [Issues](https://github.com/jhd3197/ServerKit/issues)
|
|
- Review the [Documentation](docs/README.md)
|
|
|
|
---
|
|
|
|
Thank you for contributing to ServerKit!
|