mirror of
https://github.com/usmannasir/cyberpanel.git
synced 2026-03-10 22:30:13 +01:00
Add comprehensive plugin system documentation (PLUGINS.md)
- Complete guide for plugin installation and management - Plugin development guide with code examples - Plugin structure and requirements documentation - TestPlugin reference guide - Best practices and troubleshooting sections - Author: master3395
This commit is contained in:
master3395
490
guides/PLUGINS.md
Normal file
490
guides/PLUGINS.md
Normal file
@@ -0,0 +1,490 @@
|
||||
# CyberPanel Plugin System Guide
|
||||
|
||||
**Author:** master3395
|
||||
**Version:** 1.0.0
|
||||
**Last Updated:** 2026-01-04
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
CyberPanel includes a plugin system that allows developers to extend the functionality of the control panel. Plugins can add new features, integrate with external services, and customize the user experience.
|
||||
|
||||
This guide covers:
|
||||
- Installing and managing plugins
|
||||
- Developing your own plugins
|
||||
- Plugin structure and requirements
|
||||
- Using the testPlugin as a reference
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Plugin Installation](#plugin-installation)
|
||||
2. [Plugin Management](#plugin-management)
|
||||
3. [Plugin Development](#plugin-development)
|
||||
4. [Plugin Structure](#plugin-structure)
|
||||
5. [TestPlugin Reference](#testplugin-reference)
|
||||
6. [Best Practices](#best-practices)
|
||||
7. [Troubleshooting](#troubleshooting)
|
||||
|
||||
---
|
||||
|
||||
## Plugin Installation
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- CyberPanel installed and running
|
||||
- Admin access to CyberPanel
|
||||
- Server with appropriate permissions
|
||||
|
||||
### Installation Steps
|
||||
|
||||
1. **Access Plugin Manager**
|
||||
- Log into CyberPanel as administrator
|
||||
- Navigate to **Plugins** → **Installed Plugins**
|
||||
- Click **Upload Plugin** button
|
||||
|
||||
2. **Upload Plugin**
|
||||
- Select the plugin ZIP file
|
||||
- Click **Upload**
|
||||
- Wait for upload to complete
|
||||
|
||||
3. **Install Plugin**
|
||||
- After upload, the plugin will appear in the plugin list
|
||||
- Click **Install** button next to the plugin
|
||||
- Installation process will:
|
||||
- Extract plugin files to `/usr/local/CyberCP/`
|
||||
- Add plugin to `INSTALLED_APPS` in `settings.py`
|
||||
- Add URL routing to `urls.py`
|
||||
- Run database migrations (if applicable)
|
||||
- Collect static files
|
||||
- Restart CyberPanel service
|
||||
|
||||
4. **Verify Installation**
|
||||
- Plugin should appear in the installed plugins list
|
||||
- Status should show as "Installed" and "Enabled"
|
||||
- Click **Manage** or **Settings** to access plugin interface
|
||||
|
||||
### Manual Installation (Advanced)
|
||||
|
||||
If automatic installation fails or you need to install manually:
|
||||
|
||||
```bash
|
||||
# 1. Extract plugin to CyberPanel directory
|
||||
cd /home/cyberpanel/plugins
|
||||
unzip plugin-name.zip
|
||||
cd plugin-name
|
||||
|
||||
# 2. Copy plugin to CyberPanel directory
|
||||
cp -r plugin-name /usr/local/CyberCP/
|
||||
|
||||
# 3. Add to INSTALLED_APPS
|
||||
# Edit /usr/local/CyberCP/CyberCP/settings.py
|
||||
# Add 'pluginName', to INSTALLED_APPS list (alphabetically ordered)
|
||||
|
||||
# 4. Add URL routing
|
||||
# Edit /usr/local/CyberCP/CyberCP/urls.py
|
||||
# Add before generic plugin route:
|
||||
# path('plugins/pluginName/', include('pluginName.urls')),
|
||||
|
||||
# 5. Run migrations (if plugin has models)
|
||||
cd /usr/local/CyberCP
|
||||
python3 manage.py makemigrations pluginName
|
||||
python3 manage.py migrate pluginName
|
||||
|
||||
# 6. Collect static files
|
||||
python3 manage.py collectstatic --noinput
|
||||
|
||||
# 7. Set proper permissions
|
||||
chown -R cyberpanel:cyberpanel /usr/local/CyberCP/pluginName/
|
||||
|
||||
# 8. Restart CyberPanel
|
||||
systemctl restart lscpd
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Plugin Management
|
||||
|
||||
### Accessing Plugins
|
||||
|
||||
- **Plugin List**: Navigate to **Plugins** → **Installed Plugins**
|
||||
- **Plugin Settings**: Click **Manage** or **Settings** button for each plugin
|
||||
- **Plugin URL**: Typically `/plugins/pluginName/` or `/plugins/pluginName/settings/`
|
||||
|
||||
### Enabling/Disabling Plugins
|
||||
|
||||
Plugins are automatically enabled after installation. To disable:
|
||||
- Some plugins may have enable/disable functionality in their settings
|
||||
- To fully disable, you can remove from `INSTALLED_APPS` (advanced)
|
||||
|
||||
### Uninstalling Plugins
|
||||
|
||||
1. Navigate to **Plugins** → **Installed Plugins**
|
||||
2. Click **Uninstall** button (if available)
|
||||
3. Manual uninstallation:
|
||||
- Remove from `INSTALLED_APPS` in `settings.py`
|
||||
- Remove URL routing from `urls.py`
|
||||
- Remove plugin directory: `rm -rf /usr/local/CyberCP/pluginName/`
|
||||
- Restart CyberPanel: `systemctl restart lscpd`
|
||||
|
||||
---
|
||||
|
||||
## Plugin Development
|
||||
|
||||
### Creating a New Plugin
|
||||
|
||||
1. **Create Plugin Directory Structure**
|
||||
```
|
||||
pluginName/
|
||||
├── __init__.py
|
||||
├── models.py # Database models (optional)
|
||||
├── views.py # View functions
|
||||
├── urls.py # URL routing
|
||||
├── forms.py # Forms (optional)
|
||||
├── utils.py # Utility functions (optional)
|
||||
├── admin.py # Admin interface (optional)
|
||||
├── templates/ # HTML templates
|
||||
│ └── pluginName/
|
||||
│ └── settings.html
|
||||
├── static/ # Static files (CSS, JS, images)
|
||||
│ └── pluginName/
|
||||
├── migrations/ # Database migrations
|
||||
│ └── __init__.py
|
||||
├── meta.xml # Plugin metadata (REQUIRED)
|
||||
└── README.md # Plugin documentation
|
||||
```
|
||||
|
||||
2. **Create meta.xml**
|
||||
```xml
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<cyberpanelPluginConfig>
|
||||
<name>Plugin Name</name>
|
||||
<type>Utility</type>
|
||||
<description>Plugin description</description>
|
||||
<version>1.0.0</version>
|
||||
<url>/plugins/pluginName/</url>
|
||||
<settings_url>/plugins/pluginName/settings/</settings_url>
|
||||
</cyberpanelPluginConfig>
|
||||
```
|
||||
|
||||
3. **Create URLs (urls.py)**
|
||||
```python
|
||||
from django.urls import re_path
|
||||
from . import views
|
||||
|
||||
app_name = 'pluginName' # Important: Register namespace
|
||||
|
||||
urlpatterns = [
|
||||
re_path(r'^$', views.main_view, name='main'),
|
||||
re_path(r'^settings/$', views.settings_view, name='settings'),
|
||||
]
|
||||
```
|
||||
|
||||
4. **Create Views (views.py)**
|
||||
```python
|
||||
from django.shortcuts import render, redirect
|
||||
from functools import wraps
|
||||
|
||||
def cyberpanel_login_required(view_func):
|
||||
"""Custom decorator for CyberPanel session authentication"""
|
||||
@wraps(view_func)
|
||||
def _wrapped_view(request, *args, **kwargs):
|
||||
try:
|
||||
userID = request.session['userID']
|
||||
return view_func(request, *args, **kwargs)
|
||||
except KeyError:
|
||||
from loginSystem.views import loadLoginPage
|
||||
return redirect(loadLoginPage)
|
||||
return _wrapped_view
|
||||
|
||||
@cyberpanel_login_required
|
||||
def main_view(request):
|
||||
context = {
|
||||
'plugin_name': 'Plugin Name',
|
||||
'version': '1.0.0'
|
||||
}
|
||||
return render(request, 'pluginName/index.html', context)
|
||||
|
||||
@cyberpanel_login_required
|
||||
def settings_view(request):
|
||||
context = {
|
||||
'plugin_name': 'Plugin Name',
|
||||
'version': '1.0.0'
|
||||
}
|
||||
return render(request, 'pluginName/settings.html', context)
|
||||
```
|
||||
|
||||
5. **Create Templates**
|
||||
- Templates should extend `baseTemplate/index.html`
|
||||
- Place templates in `templates/pluginName/` directory
|
||||
```html
|
||||
{% extends "baseTemplate/index.html" %}
|
||||
{% load static %}
|
||||
{% load i18n %}
|
||||
|
||||
{% block title %}
|
||||
Plugin Name Settings - {% trans "CyberPanel" %}
|
||||
{% endblock %}
|
||||
|
||||
{% block content %}
|
||||
<div class="container">
|
||||
<h1>Plugin Name Settings</h1>
|
||||
<!-- Your plugin content here -->
|
||||
</div>
|
||||
{% endblock %}
|
||||
```
|
||||
|
||||
6. **Package Plugin**
|
||||
```bash
|
||||
cd /home/cyberpanel/plugins
|
||||
zip -r pluginName.zip pluginName/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Plugin Structure
|
||||
|
||||
### Required Files
|
||||
|
||||
- **meta.xml**: Plugin metadata (name, version, description, URLs)
|
||||
- **__init__.py**: Python package marker
|
||||
- **urls.py**: URL routing configuration
|
||||
- **views.py**: View functions (at minimum, a main view)
|
||||
|
||||
### Optional Files
|
||||
|
||||
- **models.py**: Database models
|
||||
- **forms.py**: Django forms
|
||||
- **utils.py**: Utility functions
|
||||
- **admin.py**: Django admin integration
|
||||
- **templates/**: HTML templates
|
||||
- **static/**: CSS, JavaScript, images
|
||||
- **migrations/**: Database migrations
|
||||
|
||||
### Template Requirements
|
||||
|
||||
- Must extend `baseTemplate/index.html` (not `baseTemplate/base.html`)
|
||||
- Use Django template tags: `{% load static %}`, `{% load i18n %}`
|
||||
- Follow CyberPanel UI conventions
|
||||
|
||||
### Authentication
|
||||
|
||||
Plugins should use the custom `cyberpanel_login_required` decorator:
|
||||
- Checks for `request.session['userID']`
|
||||
- Redirects to login if not authenticated
|
||||
- Compatible with CyberPanel's session-based authentication
|
||||
|
||||
---
|
||||
|
||||
## TestPlugin Reference
|
||||
|
||||
The **testPlugin** is a reference implementation included with CyberPanel that demonstrates:
|
||||
|
||||
- Basic plugin structure
|
||||
- Authentication handling
|
||||
- Settings page implementation
|
||||
- Clean URL routing
|
||||
- Template inheritance
|
||||
|
||||
### TestPlugin Location
|
||||
|
||||
- **Source**: `/usr/local/CyberCP/testPlugin/`
|
||||
- **URL**: `/plugins/testPlugin/`
|
||||
- **Settings URL**: `/plugins/testPlugin/settings/`
|
||||
|
||||
### TestPlugin Features
|
||||
|
||||
1. **Main View**: Simple plugin information page
|
||||
2. **Settings View**: Plugin settings interface
|
||||
3. **Plugin Info API**: JSON endpoint for plugin information
|
||||
|
||||
### Examining TestPlugin
|
||||
|
||||
```bash
|
||||
# View plugin structure
|
||||
ls -la /usr/local/CyberCP/testPlugin/
|
||||
|
||||
# View meta.xml
|
||||
cat /usr/local/CyberCP/testPlugin/meta.xml
|
||||
|
||||
# View URLs
|
||||
cat /usr/local/CyberCP/testPlugin/urls.py
|
||||
|
||||
# View views
|
||||
cat /usr/local/CyberCP/testPlugin/views.py
|
||||
|
||||
# View templates
|
||||
ls -la /usr/local/CyberCP/testPlugin/templates/testPlugin/
|
||||
```
|
||||
|
||||
### Using TestPlugin as Template
|
||||
|
||||
1. Copy testPlugin directory:
|
||||
```bash
|
||||
cp -r /usr/local/CyberCP/testPlugin /home/cyberpanel/plugins/myPlugin
|
||||
```
|
||||
|
||||
2. Rename files and update content:
|
||||
- Update `meta.xml` with your plugin information
|
||||
- Rename template files
|
||||
- Update views with your functionality
|
||||
- Update URLs as needed
|
||||
|
||||
3. Customize for your needs:
|
||||
- Add models if you need database storage
|
||||
- Add forms for user input
|
||||
- Add utilities for complex logic
|
||||
- Add static files for styling
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Security
|
||||
|
||||
- Always use `cyberpanel_login_required` decorator for views
|
||||
- Validate and sanitize all user input
|
||||
- Use Django's form validation
|
||||
- Follow CyberPanel security guidelines
|
||||
- Never expose sensitive information in templates or responses
|
||||
|
||||
### Code Organization
|
||||
|
||||
- Keep files under 500 lines (split into modules if needed)
|
||||
- Use descriptive function and variable names
|
||||
- Add comments for complex logic
|
||||
- Follow Python PEP 8 style guide
|
||||
- Organize code into logical modules
|
||||
|
||||
### Templates
|
||||
|
||||
- Always extend `baseTemplate/index.html`
|
||||
- Use CyberPanel's existing CSS classes
|
||||
- Make templates mobile-friendly
|
||||
- Use Django's internationalization (`{% trans %}`)
|
||||
- Keep templates clean and readable
|
||||
|
||||
### Database
|
||||
|
||||
- Use Django migrations for schema changes
|
||||
- Add proper indexes for performance
|
||||
- Use transactions for multi-step operations
|
||||
- Clean up old data when uninstalling
|
||||
|
||||
### Testing
|
||||
|
||||
- Test plugin installation process
|
||||
- Test all plugin functionality
|
||||
- Test error handling
|
||||
- Test on multiple CyberPanel versions
|
||||
- Test plugin uninstallation
|
||||
|
||||
### Documentation
|
||||
|
||||
- Include README.md with installation instructions
|
||||
- Document all configuration options
|
||||
- Provide usage examples
|
||||
- Include troubleshooting section
|
||||
- Document any dependencies
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Plugin Not Appearing in List
|
||||
|
||||
- Check `meta.xml` format (must be valid XML)
|
||||
- Verify plugin directory exists in `/home/cyberpanel/plugins/`
|
||||
- Check CyberPanel logs: `tail -f /var/log/cyberpanel/error.log`
|
||||
|
||||
### Plugin Installation Fails
|
||||
|
||||
- Check file permissions: `ls -la /usr/local/CyberCP/pluginName/`
|
||||
- Verify `INSTALLED_APPS` entry in `settings.py`
|
||||
- Check URL routing in `urls.py`
|
||||
- Review installation logs
|
||||
- Check Python syntax: `python3 -m py_compile pluginName/views.py`
|
||||
|
||||
### Plugin Settings Page Not Loading
|
||||
|
||||
- Verify URL routing is correct
|
||||
- Check template path (must be `templates/pluginName/settings.html`)
|
||||
- Verify template extends `baseTemplate/index.html`
|
||||
- Check for JavaScript errors in browser console
|
||||
- Verify authentication decorator is used
|
||||
|
||||
### Template Not Found Error
|
||||
|
||||
- Check template directory structure: `templates/pluginName/`
|
||||
- Verify template name in `render()` call matches file name
|
||||
- Ensure template extends correct base template
|
||||
- Check template syntax for errors
|
||||
|
||||
### Authentication Issues
|
||||
|
||||
- Verify `cyberpanel_login_required` decorator is used
|
||||
- Check session is active: `request.session.get('userID')`
|
||||
- Verify user is logged into CyberPanel
|
||||
- Check redirect logic in decorator
|
||||
|
||||
### Static Files Not Loading
|
||||
|
||||
- Run `python3 manage.py collectstatic`
|
||||
- Check static file URLs in templates
|
||||
- Verify static files are in `static/pluginName/` directory
|
||||
- Clear browser cache
|
||||
|
||||
### Database Migration Issues
|
||||
|
||||
- Check migrations directory exists: `migrations/__init__.py`
|
||||
- Verify models are properly defined
|
||||
- Run migrations: `python3 manage.py makemigrations pluginName`
|
||||
- Apply migrations: `python3 manage.py migrate pluginName`
|
||||
|
||||
### Plugin Conflicts
|
||||
|
||||
- Check for duplicate plugin names
|
||||
- Verify URL patterns don't conflict
|
||||
- Check for namespace conflicts in `urls.py`
|
||||
- Review `INSTALLED_APPS` for duplicate entries
|
||||
|
||||
---
|
||||
|
||||
## Plugin Examples
|
||||
|
||||
### Available Plugins
|
||||
|
||||
1. **testPlugin**: Reference implementation for plugin development
|
||||
2. **discordWebhooks**: Server monitoring and notifications via Discord
|
||||
3. **fail2ban**: Fail2ban security manager for CyberPanel
|
||||
|
||||
### Plugin Repository
|
||||
|
||||
Community plugins are available at:
|
||||
- GitHub: https://github.com/master3395/cyberpanel-plugins
|
||||
|
||||
---
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- **CyberPanel Documentation**: https://cyberpanel.net/KnowledgeBase/
|
||||
- **Django Documentation**: https://docs.djangoproject.com/
|
||||
- **Plugin System Source**: `/usr/local/CyberCP/pluginInstaller/`
|
||||
- **Plugin Holder**: `/usr/local/CyberCP/pluginHolder/`
|
||||
|
||||
---
|
||||
|
||||
## Support
|
||||
|
||||
For plugin development questions:
|
||||
- Check existing plugins for examples
|
||||
- Review CyberPanel source code
|
||||
- Ask in CyberPanel community forum
|
||||
- Create an issue on GitHub
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2026-01-04
|
||||
**Author:** master3395
|
||||
Reference in New Issue
Block a user