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.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
Add Gitea integration plan documentation
Juan Denis976ba5ad372b
diff --git a/GITEA_INTEGRATION_PLAN.md b/GITEA_INTEGRATION_PLAN.mdnew file mode 100644index 00000000..bcb22ce4--- /dev/null+++ b/GITEA_INTEGRATION_PLAN.md@@ -0,0 +1,488 @@+# ServerKit Git Integration Plan++## Overview++This document outlines the plan to add integrated Git functionality to ServerKit:+1. Add new "Git" sidebar page (similar to Firewall)+2. Integrate Gitea as a first-class ServerKit feature+3. Add GitHub/GitLab webhook support for repo sync+4. Resource warnings before installation++---++## Part 1: Architecture Notes++### Current Gitea Template Status: Working++The Gitea template works correctly. Key points:+- **HTTP_PORT** (default 3000) → Auto-assigned and stored in Application.port+- **SSH_PORT** (default 2222) → Auto-assigned and stored in `.serverkit-template.json`+- Both ports are properly mapped in docker-compose.yml+- App needs startup time (~30-60 seconds) for Gitea + PostgreSQL to initialize++**Note:** Containers may take time to fully start. The UI should reflect "Starting..." status during initialization.++### SSH Access for Git Operations++SSH cannot be proxied via nginx (HTTP only). For Git SSH operations:+- Users access SSH directly: `git clone ssh://git@server:2222/user/repo.git`+- The SSH port is available in the app's `.serverkit-template.json` file+- Consider displaying SSH port prominently in the UI++### Potential Future Enhancement: Multi-Port Support++For better UX with multi-port apps like Gitea, consider:+- Adding `ssh_port` column to Application model+- Displaying both HTTP and SSH ports in app details+- This is optional - current system works fine++---++## Part 2: New Git Sidebar Feature++### Design: Git Page (Similar to Firewall Page)++**Location in Sidebar:** Infrastructure section, after Docker++**States:**+1. **Not Installed** → Show installation button with resource warning+2. **Installed but Not Configured** → Show setup wizard+3. **Running** → Show Gitea dashboard with repos++### UI Components++**File: `frontend/src/pages/Git.jsx`**++```jsx+// Structure similar to Firewall.jsx++const Git = () => {+ const [status, setStatus] = useState(null);+ const [loading, setLoading] = useState(true);+ const [showInstallModal, setShowInstallModal] = useState(false);++ // Tabs: Overview, Repositories, Settings, Webhooks+ const [activeTab, setActiveTab] = useState('overview');++ return (+ <div className="page git-page">+ {/* Not installed state */}+ {!status?.installed && (+ <div className="empty-state-large">+ <GitIcon />+ <h2>Git Server Not Installed</h2>+ <p>Install Gitea to manage your Git repositories</p>++ {/* Resource Warning */}+ <div className="resource-warning">+ <WarningIcon />+ <div>+ <strong>Resource Requirements</strong>+ <ul>+ <li>Memory: ~512MB minimum (1GB recommended)</li>+ <li>Storage: ~5GB for database + repositories</li>+ <li>Will also install PostgreSQL database</li>+ </ul>+ </div>+ </div>++ <button onClick={() => setShowInstallModal(true)}>+ Install Git Server+ </button>+ </div>+ )}++ {/* Installed state - show dashboard */}+ {status?.installed && (+ <>+ {/* Status cards, tabs, etc. */}+ </>+ )}+ </div>+ );+};+```++### Backend API Endpoints++**File: `backend/app/api/git.py`**++```python+from flask import Blueprint, jsonify, request+from flask_jwt_extended import jwt_required+from app.services.git_service import GitService++git_bp = Blueprint('git', __name__, url_prefix='/api/git')++@git_bp.route('/status', methods=['GET'])+@jwt_required()+def get_status():+ """Get Gitea installation status."""+ return jsonify(GitService.get_status())++@git_bp.route('/install', methods=['POST'])+@jwt_required()+def install():+ """Install Gitea with PostgreSQL."""+ data = request.get_json() or {}+ return jsonify(GitService.install(+ admin_user=data.get('admin_user', 'admin'),+ admin_email=data.get('admin_email'),+ admin_password=data.get('admin_password')+ ))++@git_bp.route('/uninstall', methods=['POST'])+@jwt_required()+def uninstall():+ """Uninstall Gitea and optionally remove data."""+ data = request.get_json() or {}+ return jsonify(GitService.uninstall(+ remove_data=data.get('remove_data', False)+ ))++@git_bp.route('/repos', methods=['GET'])+@jwt_required()+def list_repos():+ """List all repositories."""+ return jsonify(GitService.list_repositories())++@git_bp.route('/webhooks', methods=['GET'])+@jwt_required()+def list_webhooks():+ """List configured webhooks."""+ return jsonify(GitService.list_webhooks())++@git_bp.route('/webhooks', methods=['POST'])+@jwt_required()+def create_webhook():+ """Create a webhook for GitHub/GitLab sync."""+ data = request.get_json()+ return jsonify(GitService.create_webhook(+ source=data.get('source'), # 'github', 'gitlab', 'bitbucket'+ repo_url=data.get('repo_url'),+ local_repo=data.get('local_repo'),+ secret=data.get('secret')+ ))+```++### Git Service++**File: `backend/app/services/git_service.py`**++```python+"""Git/Gitea management service for ServerKit integrated Git."""++import os+import subprocess+import secrets+import requests+from typing import Dict, List, Optional+from app.services.template_service import TemplateService+from app.services.docker_service import DockerService++class GitService:+ """Service for managing integrated Gitea instance."""++ GITEA_APP_NAME = 'serverkit-gitea'+ GITEA_DATA_DIR = '/var/serverkit/gitea'+ GITEA_CONFIG_FILE = '/etc/serverkit/gitea.json'++ @classmethod+ def get_status(cls) -> Dict:+ """Check if Gitea is installed and running."""+ from app.models import Application++ app = Application.query.filter_by(name=cls.GITEA_APP_NAME).first()++ if not app:+ return {+ 'installed': False,+ 'running': False,+ 'http_port': None,+ 'ssh_port': None,+ 'url': None+ }++ # Check container status+ running = DockerService.is_container_running(cls.GITEA_APP_NAME)++ # Load config for ports+ config = cls._load_config()++ return {+ 'installed': True,+ 'running': running,+ 'http_port': app.port,+ 'ssh_port': app.ssh_port or config.get('ssh_port'),+ 'url': f"http://localhost:{app.port}",+ 'app_id': app.id,+ 'version': config.get('version', 'unknown')+ }++ @classmethod+ def install(cls, admin_user: str = 'admin',+ admin_email: str = None,+ admin_password: str = None) -> Dict:+ """Install Gitea as integrated ServerKit service."""++ # Check if already installed+ status = cls.get_status()+ if status['installed']:+ return {'success': False, 'error': 'Gitea is already installed'}++ # Generate secure password if not provided+ if not admin_password:+ admin_password = secrets.token_urlsafe(16)++ # Install using template service+ result = TemplateService.install_template(+ template_id='gitea',+ app_name=cls.GITEA_APP_NAME,+ user_variables={},+ user_id=1 # System user+ )++ if not result.get('success'):+ return result++ # Save config with admin credentials+ config = {+ 'admin_user': admin_user,+ 'admin_email': admin_email,+ 'admin_password': admin_password, # Should be encrypted+ 'http_port': result.get('variables', {}).get('HTTP_PORT'),+ 'ssh_port': result.get('variables', {}).get('SSH_PORT'),+ 'db_password': result.get('variables', {}).get('DB_PASSWORD'),+ 'installed_at': datetime.now().isoformat(),+ 'version': '1.21'+ }+ cls._save_config(config)++ # Update Application with SSH port+ from app.models import Application+ from app import db++ app = Application.query.filter_by(name=cls.GITEA_APP_NAME).first()+ if app:+ app.ssh_port = int(config['ssh_port'])+ db.session.commit()++ return {+ 'success': True,+ 'message': 'Gitea installed successfully',+ 'http_port': config['http_port'],+ 'ssh_port': config['ssh_port'],+ 'admin_user': admin_user,+ 'admin_password': admin_password, # Show once to user+ 'warning': 'Save these credentials - password shown only once!'+ }++ @classmethod+ def get_resource_requirements(cls) -> Dict:+ """Get resource requirements for Gitea installation."""+ return {+ 'memory_min': '512MB',+ 'memory_recommended': '1GB',+ 'storage_min': '5GB',+ 'storage_recommended': '20GB',+ 'components': [+ {'name': 'Gitea', 'memory': '~300MB', 'storage': '~100MB + repos'},+ {'name': 'PostgreSQL', 'memory': '~200MB', 'storage': '~1GB'}+ ],+ 'warning': 'Installation will spin up a PostgreSQL database container'+ }+```++---++## Part 3: GitHub Webhook Integration++### Flow++```+[GitHub/GitLab] --webhook--> [ServerKit] --sync--> [Gitea/Local Repos]+```++### Webhook Endpoint++**File: `backend/app/api/webhooks.py`**++```python+from flask import Blueprint, request, jsonify+import hmac+import hashlib++webhooks_bp = Blueprint('webhooks', __name__, url_prefix='/api/webhooks')++@webhooks_bp.route('/github/<repo_id>', methods=['POST'])+def github_webhook(repo_id):+ """Handle GitHub webhook for repo sync."""+ # Verify signature+ signature = request.headers.get('X-Hub-Signature-256')+ if not verify_github_signature(request.data, signature, repo_id):+ return jsonify({'error': 'Invalid signature'}), 401++ event = request.headers.get('X-GitHub-Event')+ payload = request.get_json()++ if event == 'push':+ # Sync changes to local Gitea+ return handle_push_event(repo_id, payload)+ elif event == 'pull_request':+ return handle_pr_event(repo_id, payload)++ return jsonify({'status': 'ignored'})++def verify_github_signature(payload: bytes, signature: str, repo_id: str) -> bool:+ """Verify GitHub webhook signature."""+ webhook_config = get_webhook_config(repo_id)+ if not webhook_config:+ return False++ secret = webhook_config['secret'].encode()+ expected = 'sha256=' + hmac.new(secret, payload, hashlib.sha256).hexdigest()+ return hmac.compare_digest(expected, signature)+```++### UI for Webhook Setup++```++----------------------------------------------------++| Add GitHub Sync |++----------------------------------------------------++| |+| GitHub Repository URL: |+| [https://github.com/user/repo.git ] |+| |+| Local Repository (in Gitea): |+| [Select or create new... v] |+| |+| Sync Direction: |+| ( ) GitHub -> ServerKit (mirror) |+| ( ) Bidirectional |+| ( ) ServerKit -> GitHub (push) |+| |+| Webhook URL (copy this to GitHub): |+| +----------------------------------------------+ |+| | https://yourserver.com/api/webhooks/github/ | |+| | abc123xyz | |+| +----------------------------------------------+ |+| [Copy] |+| |+| Webhook Secret: |+| +----------------------------------------------+ |+| | •••••••••••••••••• | |+| +----------------------------------------------+ |+| [Generate New] [Copy] |+| |+| [Cancel] [Create Webhook] |++----------------------------------------------------++```++---++## Part 4: Implementation Order++### Phase 1: Git Page Foundation (Priority: High)+1. [ ] Add "Git" to sidebar in Sidebar.jsx+2. [ ] Create Git.jsx page component+3. [ ] Create _git.less styles+4. [ ] Create git_service.py backend+5. [ ] Create git.py API blueprint+6. [ ] Register blueprint in __init__.py++### Phase 2: Integrated Gitea (Priority: Medium)+1. [ ] Create Gitea installation flow with resource warning+2. [ ] Store Gitea config separately from regular apps+3. [ ] Add Gitea-specific nginx config generation+4. [ ] Add SSH port display in UI+5. [ ] Create uninstall flow++### Phase 3: Webhook Integration (Priority: Medium)+1. [ ] Create webhook database model+2. [ ] Create webhooks API endpoints+3. [ ] Create webhook verification logic+4. [ ] Create UI for webhook management+5. [ ] Add GitHub webhook handler+6. [ ] Add GitLab webhook handler (optional)++### Phase 4: Polish (Priority: Low)+1. [ ] Add repository browsing in Git page+2. [ ] Add commit history viewer+3. [ ] Add branch management+4. [ ] Add user/team management integration++---++## Part 5: File Structure++```+backend/+├── app/+│ ├── api/+│ │ ├── git.py # NEW - Git API endpoints+│ │ └── webhooks.py # NEW - Webhook handlers+│ ├── models/+│ │ └── webhook.py # NEW - Webhook model+│ └── services/+│ └── git_service.py # NEW - Git/Gitea service+│+frontend/+├── src/+│ ├── components/+│ │ └── Sidebar.jsx # MODIFY - Add Git item+│ ├── pages/+│ │ └── Git.jsx # NEW - Git page+│ ├── services/+│ │ └── api.js # MODIFY - Add git endpoints+│ └── styles/+│ └── pages/+│ └── _git.less # NEW - Git page styles+```++---++## Part 6: Database Changes++```sql+-- New table: webhooks (for GitHub/GitLab sync)+CREATE TABLE webhooks (+ id INTEGER PRIMARY KEY,+ name VARCHAR(100) NOT NULL,+ source VARCHAR(50) NOT NULL, -- 'github', 'gitlab', 'bitbucket'+ source_repo_url VARCHAR(500) NOT NULL,+ local_repo_id INTEGER,+ secret VARCHAR(100) NOT NULL,+ sync_direction VARCHAR(20) DEFAULT 'pull', -- 'pull', 'push', 'bidirectional'+ last_sync_at DATETIME,+ created_at DATETIME DEFAULT CURRENT_TIMESTAMP,+ is_active BOOLEAN DEFAULT TRUE+);++-- New table: git_config (for integrated Gitea settings)+CREATE TABLE git_config (+ id INTEGER PRIMARY KEY,+ app_id INTEGER REFERENCES applications(id),+ admin_user VARCHAR(100),+ http_port INTEGER,+ ssh_port INTEGER,+ version VARCHAR(20),+ installed_at DATETIME,+ UNIQUE(app_id)+);+```++---++## Summary++| Feature | Status | Priority |+|---------|--------|----------|+| Git sidebar page | Need implementation | High |+| Resource warning UI | Need implementation | High |+| Integrated Gitea installation | Need implementation | High |+| GitHub webhook sync | Need implementation | Medium |+| GitLab webhook sync | Need implementation | Low |+| Repository browser in UI | Need implementation | Low |++This plan provides a roadmap for adding a fully integrated Git feature to ServerKit with resource warnings and webhook support for syncing with GitHub/GitLab repositories.