If you are interested to extend functionality of CyberPanel core, this guide can help you get started by explaining how you can extend CyberPanel by creating and adding plugins.
If you are an experienced developer, you can just look at the small example plugin and move from there. Each CyberPanel application (Django app) contains a signal file, that you can use to hook into events. For websiteFunctions app, signals file is located here. Here is an small example of how an event from this file is used to do something else in example plugin mentioned above.
Prerequisites
- Python
- Django
- HTML (Basic)
- CSS (Basic)
You should have clear understanding of Python Programming Language and Django framework, because in this guide we assume that you have experience with both of these technologies.
Note: You can use plain JavaScript in your plugins or any JavaScript framework, it is totally dependent on you. You just have to follow the norms of Django framework, because CyberPanel plugin is just another Django app.
Step 1: Set up your Development Environment
You first need to set up a local development environment, you can clone CyberPanel from GitHub repo.
git clone https://github.com/usmannasir/cyberpanel/ --single-branch v1.7.2-plugin
Once the repo is cloned locally, you need to first create a simple Django app.
cd v1.7.2-plugin
django-admin startapp pluginName
Now this will create a Django app and default directory structure in pluginName directory**,**the plugin name is of great importance, so make sure you choose it wisely. Once Django app is created, you need to define a meta file for your plugin, so that CyberPanel can read information about your plugin, you can put this meta file inside this app root folder.
cd pluginName
nano meta.xml ## This will open the editor, you can paste following in this file
<?xml version="1.0" encoding="UTF-8"?>
<cyberpanelPluginConfig>
<name>customplugin</name>
<type>plugin</type>
<description>Plugin to make custom changes</description>
<version>0</version>
</cyberpanelPluginConfig>
Step 2: Creating a signal file and adjusting some settings
Once your development environment is set up, you need to create signals file. You can name this file anything, but in our example plugin we’ve called it signals.py, after creating you can leave this file empty for now. Let see how some of your files should look like inside the plugin folder.
apps.py
In your apps.py file, you need to import this signals file inside the ready function.
def ready(self):
import signals
If you have named this file something else, please adjust the names accordingly, you can see the example file here.
init.py
You need to specify a default_app_config variable in this file, such as
default_app_config = 'examplePlugin.apps.ExamplepluginConfig'
You can adjust the names according to your plugin name. Example can be seen here.
urls.py
Inside your app root directory create urls.py, and paste this content
from django.conf.urls import url
import views
urlpatterns = [
url(r'^
You can have as many urls in this file (with corresponding views functions), but this one URL defination is very important, replace examplePlugin with your plugin name, such as
url(r'^
This is very important for CyberPanel to register your plugin page. In this view you can load the default page of your plugin (or settings file for your plugin). With this URL definition your plugin will not work.
Some optional files
Plugin installer (we will discuss how to install plugins later) will not take care of any models that you create in your project models.py file, so if you create some models you can write your own logic to apply these models to database, for this very reason you can create two files.
They can be python code or plain bash script.
- pre_install (If this exists it will be executed before installation of plugin)
- post_install (If this exists it will be executed after installation of plugin)
Place these files in same folder with your other files that you create above. If your file is a python code, don’t forget to include this line at top #!/usr/local/CyberCP/bin/python2
This completes directory structure of your plugin, if you got confused along the way, you can look at the example plugin. You are allowed to create anything that you can do with a normal Django application such as create views and templates.
Step 3: Responding to Events
Once you are done with Step 2 above, you want to plug into the events fired by CyberPanel core. You can also create a plugin that does not depend upon signals (in other words don’t want to interact with core). But this step will help you understand how you can respond to various events happening in the core.
To get list of events in websiteFunction you can visit the signal file (this core applications deals with creation and deletion of websites, child-domains and domain alias). Some events are:
- preWebsiteCreation: This is fired before CyberPanel starts the creation of website, so you can use this event to stop further execution of core code, we will discuss that later.
- postWebsiteDeletion: This is fired after core finished the deletion of website.
You can visit the file for more events, they are self-explanatory. So how you can respond to these event, you may remember that in our plugin we created an signals.py file. You can respond to events in that file. Let see how we can respond to postWebsiteDeletion event.
from django.dispatch import receiver
from django.http import HttpResponse
from websiteFunctions.signals import postWebsiteDeletion
from plogical.CyberCPLogFileWriter import CyberCPLogFileWriter as logging
@receiver(postWebsiteDeletion)
def rcvr(sender, **kwargs):
request = kwargs['request']
logging.writeToFile('Hello World from Example Plugin.')
return HttpResponse('Hello World from Example Plugin.')
From your event handler functions you can either return HttpResponse object or int 200. But behavior will change depending on what you have returned. If you have returned HttpResponse object, CyberPanel core will stop further processing, and consider your response as final and return it to browser. However if you return int 200, CyberPanel core will continue processing, assuming that events was successfully executed.
Step 4: Packing, Shipping and Installing Plugin
You need to package your plugin so that it can be installed on CyberPanel. After completing your plugin, just zip your Django app. Zip file name should be your plugin name i.e examplePlugin.zip, otherwise installation will fail.
To install your plugin you can use plugin installer located at /usr/local/CyberCP/pluginInstaller, use following commands to install and remove your plugin.
Installation
First upload your plugin at /usr/local/CyberCP/pluginInstaller
cd /usr/local/CyberCP/pluginInstaller
python pluginInstaller.py install --pluginName examplePlugin
Uninstall
cd /usr/local/CyberCP/pluginInstaller
python pluginInstaller.py remove --pluginName examplePlugin
Beautiful names
We’ve released an official plugin called Beautiful names, you can read more. Plugin installation facility is in beta and not available with official install yet, to install plugins compatible version you can install CyberPanel via
sh <(curl https://mirror.cyberpanel.net/install-test.sh || wget -O - https://mirror.cyberpanel.net/install-test.sh)