Documentation


What is Kernl?


Kernl is a service that provides private plugin and theme updates for WordPress. This is best illustrated with an example. Lets say that you have a brand new plugin that you are selling. Since you are selling this plugin you can't host it via WordPress.org because otherwise people could download it for free.

Like any good developer, you want your plugin to be integrated with the automatic update functionlity of WordPress. Thats where Kernl comes into play. By simply adding a file to your plugin and a short code snippet you'll be able to host your updates through Kernl instead of WordPress, therefore giving your users the best possible experience and timely updates.


Adding Private Updates to my Plugin


Adding private updates to your plugin is as easy as following the interactive instructions on the dashboard. We'll detail exactly what happens here so you are aware of the whole process.

The first step is to create a plugin entry on Kernl. This allows us tie a unique URL to your plugin so we don't get our wires crossed.

There are a lot of options when setting up your plugin, but we won't cover all of them just yet. If you want to save a ton of time, you should check out our Continuous Deployment service. It's included with your Kernl subscription.

Once you have a plugin set up, the next step is to download the plugin updater code. This is a PHP file that will be included in your plugin. It essentially tells your plugin how to check for and download updates from Kernl. It can be downloaded here or from the interactive setup on the dashboard.

After you have placed the plugin_update_check.php file in your plugin root directory, you need to add a snippet of code to the main file of your plugin. It looks like this:

require 'plugin_update_check.php';
$MyUpdateChecker = new PluginUpdateChecker_2_0 (
   'https://kernl.us/api/v1/updates/[[your-plugin-uuid]]/',
   __FILE__,
   'my-plugin-slug',
   1
);
// $MyUpdateChecker->license = "aKernlLicenseKey";  <---- optional!
// $MyUpdateChecker->remoteGetTimeout = 5; <--- optional

[[your-pluign-uuid]] should be replaced with the UUID of your plugin, which can be found on the plugin list page.

my-plugin-slug should be replaced with slug of your plugin. This is the same slug that you entered when you created your plugin. This slug should also be the name of your plugin's directory.

license should be uncommented only if you choose to use Kernl license management.

remoteGetTimeout By default this is set to 10 seconds. If you would like updates to fail faster if there happens to be a problem with Kernl, lower this number. How low you can go with this depends a lot on the location of your server and how close it is to Kernl.

Once all that is completed, zip your plugin up as if you were distributing it to your users and upload it as a version to Kernl. After that distribute a copy of the plugin you uploaded and then Voila! Your customers will automatically receive any updates you post to Kernl in the future.

An example plugin can be viewed on BitBucket here.


Adding Private Updates to My Theme


Adding private updates to your theme is as easy as following the interactive instructions on the dashboard. We'll detail exactly what happens here so your are aware of the whole process.

The first step is to create a theme entry on Kernl. This allows us tie a unique URL to your theme so we don't get our wires crossed.

There are a lot of options when setting up your theme, but we won't cover all of them just yet. If you want to save a ton of time, you should check out our Continuous Deployment service. It's included with your Kernl subscription.

Once you have a theme set up, the next step is to download the theme updater code. This is a PHP file that will be included in your theme. It essentially tells your theme how to check for and download updates from Kernl. It can be downloaded here or from the interactive setup on the dashboard.

After you have placed the theme_update_check.php file into your theme root directory, you need to add a snippet of code to the main file of your theme. It looks like this:

require 'theme_update_check.php';
$MyUpdateChecker = new ThemeUpdateChecker(
    'my-theme-slug',
    'https://kernl.us/api/v1/theme-updates/[[your-theme-uuid]]/'
);
// $MyUpdateChecker->license = "aKernlLicenseKey";  <---- optional
// $MyUpdateChecker->remoteGetTimeout = 5; <---- optional

[[your-theme-uuid]] should be replaced with the UUID of your theme, which can be found on the theme list page.

my-theme-slug should be replaced my your theme's slug. This is the same slug you entered when you added your theme. This slug should also be the name of your theme's directory.

license should be uncommented only if you choose to use Kernl license management.

remoteGetTimeout By default this is set to 10 seconds. If you would like updates to fail faster if there happens to be a problem with Kernl, lower this number. How low you can go with this depends a lot on the location of your server and how close it is to Kernl.

Once all that is completed, zip your theme up as if you were distributing it to your users and upload it as a version to Kernl. After that, give your customers a copy of the theme you uploaded and then Voila! They will receive any updates you post to Kernl in the future.

An example theme can be viewed on BitBucket here.


WordPress MU (Network Installs)


Due to the way that Wordpress handles updates and transients with network installs, Kernl has a tendency to be flaky when it comes to receiving updates on WordPress MU. Unfortunately we aren't able to fix the issue because it is an issue with WordPress itself and we lack the time to contribute to WordPress Core.

If you manage your own WPMU network and would like to use Kernl, it's possible to write a custom plugin that will handle updates for you, although we ourselves do not have one available.

Theme Troubleshooting


On rare occassions your theme update might fail. Generally you can try the update again and it will work, but there is one situation where that isn't quite good enough.

If you find that when your theme is updating it renames the directory into something odd (for example: download-xxxx), you need to make sure that your theme is contained within a folder.

An example of a theme layout that may cause this is:

// Bad theme layout
- styles.css
- functions.php
- header.php
- .... other files.

And an example of theme layout that fixes this issue is:

// Good theme layout
- my-theme-slug/
    - styles.css
    - functions.php
    - header.php
    - .... other files.

In summary, make sure that when you package your theme it is in a folder named after your slug. If it isn't, the update will fail.

More information on this potential bug can be found at on the Kernl bug tracker and on the Wordpress bug tracker.


License Management


As is often the case in WordPress development you want to sell your hard work. But how do you keep people from downloading updates for free? Thats where Kernl License Management comes in. Kernl license management only allows someone with a valid license to download updates of your theme or plugin.

To enable license management, check the "Use Kernl to validate Licenses?" in the License Management tab in your plugin or theme settings. After that, you manage licenses via the "License Management" button in main application menu. See the examples above for adding a license to the plugin and theme update checkers.

If you aren't sure how to get customers to enter their license, you should check out the WordPress Setting API. It provides an easy to way to quickly add fields to the existing WordPress settings pages.

Note: Please use only Envato license validation OR regular Kernl license management. Using both will default to ignoring the Envato validation.


Envato Purchase Code Validation


Kernl supports validating purchase codes against Envato. To enable this, log in to Kernl and go to your Profile. From there fill in the "Envato API Token" field using the token generated at 'https://build.envato.com/create-token/'.

To enable Envato purchase code validation check the "Validate Envato Purchase Code?" box in the plugin or theme creation form. From now on that plugin or theme will require a valid Envato purchase code to see updates. See the examples above for adding a purchase code to the plugin and theme update checkers.

Note: Please use only Envato purchase code validation OR regular Kernl license management. Using both will default to ignoring the Envato validation.


Easy Digital Downloads Validation


Kernl supports validating licenses against your Easy Digital Downloads(EDD) install. To enable this, go to your plugin or theme and check the "Validate Easy Digital Downloads License?" box.

Next, fill in the "EDD Item ID" text input with the EDD item id that you are validating. After that, fill in the "EDD URL" with the site where EDD is installed. If you have EDD installed on "yourdomain.com", then you would enter "http://yourdomain.com" in this box.

In the Kernl instantiation code, just set the 'purchaseCode' to the EDD license that should be validated.

Note: Please use only Easy Digital Downloads validation OR regular Kernl license management. Using both will default to ignoring the Easy Digital Downloads validation.


Continuous Deployment with BitBucket, GitHub, & GitLab


Continuous deployment(CD) is a process where you are constantly building and deploying code to some environment. In most modern development setups this is done via a "push to build" system, where you push your latest code to a Git repository and then a post-commit hook is trigerred that lets your CD server know about the change. In the WordPress plugin and theme communities this can be tough because the environment is often someone elses server. So how do you deploy to that? Thats where we come in.

Kernl lets you hook up your BitBucket, GitHub, and GitLab accounts to our build system, allowing us to automatically receive your changes and then build and deploy your project for you.


Connecting with GitLab


The process for connecting your Gitlab.com account to Kernl takes a few steps. The first is to go to the "Continuous Deployment" page in Kernl (see left-hand menu once you've logged in).

After that you need to click the "Connect with GitLab" button. You will then be prompted to enter a GitLab "Personal Access Token". You can generate one for Kernl by...

1: Going to your GitLab account

2: Clicking your profile picture in the upper-right corner

3: Going to Settings

4: Clicking the Access Tokens menu

5: Create the access token. It can be named anything you'd like, and leave the expiration blank. Be sure to select the "api" scope.

6: Once your token has been created, copy and paste it into the modal window that Kernl presented you with. Click "Save and Verify" to continue.

If at any point the process for setting up CI gets confusing, please reach out to jack@kernl.us. We're happy to help get you set up.

Connecting with BitBucket and GitHub


The first step in getting Continuous Deployment (CD) setup is to connect your Kernl account with your BitBucket or GitHub account. This is accomplished via the the "Continuous Deployment" button in the left-hand menu.

After that you need to click the "Connect with Bitbucket" or the "Connect with GitHub" button. This will send you out to authorize Kernl to access your account.

After you have authorized Kernl, you'll be sent back to us so you can start the next step.

If at any point the process for setting up CI gets confusing, please reach out to jack@kernl.us. We're happy to help get you set up.


Selecting your Repository & Branch


Now that you've connected Kernl with your BitBucket, GitHub, or GitLab account, the next step is telling Kernl what repository and branch we should watch for incoming changes on. This is pretty easy and is done via the "Edit Plugin" or "Edit Theme" window. To get there, go to the plugins or themes section and click "Edit" on the project you would like to add CI services to. After that, click the "CD / CI Services" tab.

Special note for BitBucket users: BitBucket's API won't allow us to fetch repositories that have been shared with you (even if you are the admin). To get around this, have the owner create a team and then add the repository to the team. Once they do that, you can be added to the team and see the repository.

Now select what repository you would like to build from.

After you have selected a repository, directly below that field is the branch selector. Kernl will automatically populate this field with the branches of your project. Select the branch you would like Kernl to build from.

If you select the "Automatically manage deploy keys and webhooks?" checkbox Kernl will automatically manage Kernl deploy keys and webhooks for the repository that you select. This currently only works for Github and Gitlab. For Bitbucket you will need to manage deploy keys and webhooks manually using the process below. If you feel so inclined, you may do the same thing for Github and Bitbucket.

Its important to note that you must upload an initial version of your plugin or theme to Kernl manually via the web interface. This version must include the kernl.version file that you will learn about below. If you don't do this, the build will fail.


Adding a WebHook (BitBucket)


If you are using Bitbucket the next step to get continuous delivery wokring is to add a webhook in the BitBucket admin. To do this, you need to go to your repository settings section on Bitbucket. The URL for this will look something like 'https://bitbucket.org/[username]/[repository]/admin/'.

Once there, click the "Webhooks" link.

Now you can click the "Add webhook" button. Enter "Kernl Push To Build" for the name, and 'https://kernl.us/api/v1/webhooks/bitbucket' for the URL. The "status" field should be checked. Keep the "Triggers" radio button selected on "Repository push". After you press save, every push that happens to your repository will send a notification to Kernl to see if we should build. We will only build on on the branch you defined above.

Next, you'll need to add a deployment key.


Adding a WebHook (GitHub)


If you choose to not have Kernl automatically manage your webhooks, the next step is to add a webhook to your repository. To do this, you need to go to your repository settings area.

Now you can click the "Webhooks" button.

Next, create a new webhook by clicking the "Add webhook" button. After that, fill out the "Payload URL" field with 'https://kernl.us/api/v1/webhooks/github', set the content type to 'application/json', leave everything as is and press "Add webhook" at the bottom.

Now that the webhook is installed every push that happens to your repository will send a notification to Kernl to see if we should build. We will only build on the branch you defined above.


Adding a WebHook (GitLab)


If you choose to not have Kernl automatically manage your webhooks, the next step is to add a webhook to your repository. To do this, you need to go to your repository settings area in Gitlab.

Now click the "Integrations" tab.

Next, create a new webhook by filling out the "URL" field with 'https://kernl.us/api/v1/webhooks/gitlab', make sure "Push events" is checked, and then press "Add webhook" at the bottom for the form.

Now that the webhook is installed every push that happens to your repository will send a notification to Kernl to see if we should build. We will only build on the branch you defined above in "Selecting Your Repository & Branch" section.

Next, you'll need to add a deployment key.


Adding a Deployment key (BitBucket & GitLab Only)


If you've chosen to have Kernl auotomatically manage your deployment keys you may skip this step.

Before Kernl can access your code, you need to create a deployment key for us. To do that, go to the "Continuous Deployment" menu in Kernl. In the right panel, click the blue button that says "Manage Deployment Keys".

From here, click "Add Deployment Key" and select the repository which you are adding keys for. Each repository that you have will require a separate deployment key.

Now that you've created a deployment key, you'll see it show up in the deployment key list. Copy the whole key and add it to you repository in BitBucket or GitLab.

In BitBucket, you need to go to Settings/Access Keys.

In GitLab you need to go to your project's settings, Repository, and then Deploy Keys.

Adding a deployment key is only required for BitBucket & GitLab.


Adding a kernl.version file


The final step in getting CI support set up is adding a kernl.version file to your project's root directory. The kernl.version file simply contains the version of your plugin or theme. This should correspond to the version defined in your plugin or theme. For instance, the Kernl Example Plugin's "kernl.version" file looks like this:

2.1.3

Thats it. If the version in the kernl.version file is older or the same as the current version on Kernl, no build will happen. If its newer (2.1.1 -vs- 2.1.3), then a new build will be triggerred. You will then receive an email with a notification of the build. If you want to verify the build, you can view it in your project's version area on the Kernl website. An example kernl.version file can be viewed here.

Note about kernl.version: The reason why we use a kernl.version file instead of parsing files and pulling versions from there is to make this system extendable. You'll see what we mean as we add more features.

The final step before the build actually works is to manually upload a copy of your plugin or theme (that contains a kernl.version) to Kernl. THE BUILD WILL FAIL IF YOU DO NOT FOLLOW THIS STEP In the future Kernl will handle building the initial version for you, but right now it must be done manually.


Webhook Changelogs


Kernl supports changelogs on plugins via it's web interface. However if you'd like to automatically populate the changelog for the plugin via a webhook push, you need to add a changelog.json file.

The format for the changelog.json file is a simple JSON object, where the key is the version that you are pushing and the value is an object containing changelog information. For example, if your kernl.version file contains:

2.1.0

Then your changelog.json file might look like:

{
"2.0.0" : {
     "description" : "Version 2 is live!",
     "requires" : "4.7.0",
     "tested" : "4.7.3",
     "upgrade_notice" : "A brief reason why you should upgrade"
},
"2.1.0" : {
     "description" : "We made some more great changes.",
     "requires" : "4.7.1",
     "tested" : "4.7.3",
     "upgrade_notice" : "Another brief reason why you should upgrade"
}

In this case, your changelog for 2.1.0 would read "We made some more great changes.". If you don't add a changelog for the version that you've pushed, the changelog field will remain blank.

The changelog description field can contain basic HTML elements such as ul, ol, and strong. More complicated elements are stripped out automatically by WordPress.

The .kernlignore File


Sometimes there are files that you don't want included in your automatic Kernl builds. For example, a .gitignore file, or an entire build/ directory. By creating a .kernlignore file in the root of your plugin or theme you can selectively remove files and folders from the build process.

To get started, place a .kernlignore file in the root of your plugin or theme. You can then fill it with files and directories that you want excluded from the build process.

.gitignore
build/js
build/css
passwords.txt
directory/file-to-exclude.js

Slack Notifications


For everyone using Slack, Kernl now integrates with Slack to let you know when new versions of plugins and themes are released.

To get started, go to the slack channel you would like release notification in and add the "Incoming Webhook" integration. Once created, Slack will give you a URL for incoming webhooks. Copy that URL.

Next, log in to Kernl and go to your profile (upper left under your name). Paste the URL into the "Slack Webhook URL" field and save.

Thats it. Your Slack channel will now be notified when a new plugin or theme release happens. This works for both manually uploaded files as well as those built via continuous deployment.


Webhook Notifications


Webhooks are a popular way of notifying existing systems that a change has occurred on the source system. In Kernl's case, you can define a list of URLs that get notified whenever a new version of your plugin or theme is published on Kernl.

To get started create or edit a plugin/theme of your choosing. In the "CI/CD Services" tab, there is a field for "Webhook URLs" that you can fill with URLs that should be notified when a new version goes out. You can have as many urls as you want in a comma separated list. Example:

https://kernl.us,https://sweet-wp-plugins.com,http://www.google.com

Kernl will notifiy the endpoints specified above with a POST request and a payload that looks like:

{
type: 'theme', // can be either 'plugin' or 'theme'
name: 'Kernl Example Theme', // the name of the published plugin or theme
version: '1.1.3', // the version that was just published
downloadUrl: 'https://kernl.us/api/v1/theme-updates/586ee8ce0b707b3ebbc1f9cc/download',
createdAt: Sun Feb 19 2017 11:33:38 GMT-0500 (EST)
}

Webhook notifications work for versions published via the Kernl web app as well as versions created automatically via Git pushes.


Free Open Source Update Hosting


Kernl itself is built on top of open source products. We firmly believe in free software and have benefited from it greatly, so we want to return the favor. If you are hosting a free, non-commercial, open source plugin or theme, contact us.