One of the great features of OpenShift 3 is the ability to use the Source-to-Image functionality to build docker based images on the fly from existing source code. In order to use this feature, you simply need to select to use a builder image and then create a new build as shown in the following image:
However, it would also be nice if you could trigger automated builds any time the code in your repository is updated. I am happy to state that we support this via webhooks and specifically github hooks. The process works like this, when a commit is pushed to your repository, GitHub makes a call out to OpenShift to alert the platform that new source code is available. The platform then begins the S2I process to clone the repository and start a new build. Once the build has finished, the new code will be deployed to your project.
That being said, a lot of developers are using the awesome all-in-one virtual machine or the official CDK and that presents a problem when considering the usage of webhooks. Specifically, the all-in-one and CDK local environments are not publicly addressable from the outside internet because it typically runs on a private IP address that is only available on your local subnet (10.2.2.2 for example). To illustrate this, the GitHub webhook URL for a project I am working on is:
https://10.2.2.2:8443/oapi/v1/namespaces/webhook/buildconfigs/mlbparks/webhooks/UhcUH5Em/github
As you can see in the above example, this endpoint is private and GitHub will not be able to make a call as it resides on my private network.
Using Ultrahook
Luckily there is a tool available that will allow you receive webhooks on your private network that is both quick and easy to get started with. For the remainder of this blog post, I am going to walk you through getting ultrahook up and running on your local machine. If you are not a fan of using a 3rd party tool, such as ultrahook, the process is pretty straightforward and you should be able to implement your own with minimal code. I would even suggest running your webhook server on OpenShift Online! Graham, from my team, wrote his own last week in Python and should have a post up fairly quickly showing his implementation.
The first thing you want to do is head over to the ultrahook site and click the Get Started Now button as shown in the following image:
Once you have signed up for an account and created your unique namespace, you need to install the ultrahook gem on your local machine. To use ultrahook, you will need to have the popular RubyGems system installed on your machine. I am not going to cover how to install this as it’s not in scope for this post but if you don’t have it, head over to the official site and follow the instructions. Once you have RubyGems ready to go, simple enter in the following command:
$ gem install ultrahook
You should see output similar to the following:
Fetching: ultrahook-0.1.4.gem (100%)Successfully installed ultrahook-0.1.4
Parsing documentation for ultrahook-0.1.4
Installing ri documentation for ultrahook-0.1.4
Done installing documentation for ultrahook after 0 seconds
1 gem installed</span>
Once you have ultrahook installed, you will also want to create a .ultrahook file in your home directory so that you don’t have to pass your API each time you use the tool. On Linux or OS X the command is as follows:
echo "api_key: ‘mysupersecretkey" > ~/.ultrahook
Now we are ready to set up our webhook to build automatically based on changes to our repository. The first thing we want to do is find the unique endpoint for our specific application. To do this, browse to the OpenShift web console and select the project you want to use for automated builds. Once you are on the project overview page, click on browse and then build. Lastly, select the BuildConfig name as shown in the following image:
On the BuildConfig overview page, click on Configuration as shown in the following image:
As finally, click on the GitHub URL copy icon to copy the URL to your clipboard:
Now that we have our endpoint URL, we need to setup ultrahook to proxy events to our OpenShift instance. In order to do that, simply enter in the following command ensuring you are are using the correct URL for your project:
$ ultrahook github
https://10.2.2.2:8443/oapi/v1/namespaces/webhook/buildconfigs/mlbparks/webhooks/UhcUH5Em/github
Now all you need to do is set up the webhook on your github project. To do this, browse to your project on GitHub and select settings as shown in the following image:
On the settings page, select WebHooks & Services and then click on Add webhook.
On the next page, you will need to enter in the URL for your webhook. This URL is the unique namespace for your ultrahook account as well as the name you provided when running the ultrahook command on your local machine. For example, if my namespace was called mlbparks and using the command previously in this blog post, my URL would be github.mlbparks.ultrahook.com:
Summary:
In this blog post, we used a free tool called Ultrahook in order to configure automated builds based upon changes in our source code repository while running OpenShift 3 on our local machine. We learned how to create an ultrahook account, install it locally and then configured our github project to make use of the new hook. The only left for you to do now is make something great and watch OpenShift automatically create and deploy a docker image of your application.
I have also created a video that showcases how to get all of this running: https://youtu.be/--wNO4lV6WA
Categories
