In an earlier blog, we showed you the newly launched ClickStart feature. Harpreet wrote about the productivity boosts offered by the ClickStart application templates feature. The essence of that earlier blog is: ClickStarts are like Maven archetypes, but on some serious steroids. A ClickStart template sets up the project code, sets up the corresponding repository, Jenkins job, sets up the database and deploys the application. So in one click, developers have a development to deployment environment ready. They can just leap in and start coding. See my earlier blog that shows the steps to follow to create an application.
Let us delve into how to create your own ClickStart. Creating your own ClickStart is a handy way to show off your own handiwork, or demo a framework, language, etc. It really isn’t that hard, and this guide will walk you through it.
First, you will want to decide what type of ClickStart this is - is it a “full stack” application with continuous deployment (i.e., has a source repo, build, app) - does it have a database or not, or is it simply a prebuilt app you want to share with the world?
Based on this, the easiest way is to pick a currently working ClickStart, fork it in GitHub into your account and then make your changes.
Some Starting Examples to Fork and Build from:
- Basic servlet app
- Scala and Lift with a database - https://github.com/CloudBees-community/lift_template
- Java EE 6 with database - https://github.com/CloudBees-community/jboss-db-example
- Simple WAR app (no source repo, no build, no database) - https://github.com/CloudBees-community/simple-war-clickstart
So the steps: 1) fork one of the above 2) make your awesome changes and test them 3) publish your awesome ClickStart on the web, or contact cloudbees (@cloudbees on twitter, open a support ticket) if you want us to add it to the official “gallery” of ClickStarts for people to build on.
Let’s look at the simplest template for the clickstart.json format (everything is driven off that json file) - this one simply deploys a war file to a container. No database, no build.
“name”: “Simple - WAR”,
“description”: “Simple war deployed through clickstart”,
This is pretty simple - the interesting bit here is that the “app-package” field refers to a publicly accessible WAR file - in this case it will deploy it in a Tomcat app container.
Full Stack ClickStart with Continuous Deployment, App, Source Repo and a Database!
The whole enchilada.
OK, now lets clone the Lift web example from above and take a look at its clickstart.json file for more details on a full stack example:
“name”: “Scala and Lift”,
“description” : “Lift is a highly scalable framework for web apps in scala.”,
“icon” : “https://awesomeicon”,
“doc-url” : “https://github.com/CloudBees-community/lift_template/blob/master/README.md”,
Relax, it really is simple. Let me take you through the fields:
- id: just make this something unique (could be the URL to your GitHub repo)
- source: if this ClickStart has a source repo to clone - put it in here. It has to be a public anonymous URL (no authentication) for the CloudBees forge to clone. If this does not appear, no source will be cloned (and no point in having a build job either!)
- name: this will be shown in the launch GUI - be witty, but brief!
- description: a longer description of your ClickStart, what it will do.
- icon: an optional link to an icon - similar in size to this one: https://a248.e.akamai.net/assets.github.com/images/gravatars/gravatar-140.png (will be scaled to that). Should be https to avoid page warnings
- doc-url: an optional link to a longer description - a GitHub README is just fine for this.
- runtime: currently this can be either “tomcat” or “jboss” - more available soon.
- databases: (optional) this is a list of databases the application uses (typically only one - don’t get greedy!). MySQL is currently the only supported. The name used is bound to your application just the same as if you went “bees app:bind -db DBNAME -a MYAPP_ID -as LiftDB” from the command line (depends on the framework as to how this exposed)
- build-with-jenkins: at the time of this blog, only Maven builds are supported (so not much to say here) - but expect this to change very soon! So, check the pom.xml for the project build configuration if you are using Jenkins in your ClickStart.
Testing Your ClickStart
If you have forked one of the above ClickStarts - or really any ClickStart you found that you know works - and made your changes, and you want to see it work, it is quite simple.
Put the following link in your browser
https://grandcentral.cloudbees.com/?CB_clickstart=https://<path to your clickstart.json>
or embed the link along with a snappy image:
You can put this image on your own repository/website if you like. Note that the path to the clickstart.json must be a publicly accessible URL returning json (e.g., the raw url - https://raw.github.com - that GitHub will give you works great). This will launch the ClickStart ready to try out. If it can’t parse it, or if it fails to run, it should tell you why.
Of course, we would love to include the ClickStart in our gallery (we will fork your repo into one on the CloudBees Community site on GitHub). When you are happy, contact someone at CloudBees, and we may be able to add it to the official gallery - and glory is yours!
After ClickStart App Created - Custom Welcome Message
After your ClickStart has been run by a user - it is nice to show them a “Hello World” page that has instructions on how to fork the repo, make changes etc. You will note in the CloudBees ClickStarts that in the main “index.html” page there is some html/script to show this. Take a look at this page and look for the section with the comment “<!— welcome to clickstart message —>” for a very simple example of this. Other ClickStarts will do something similar. Different frameworks cunningly hide where the index.html/main page is, so you may need to poke around a bit.
ClickStart is brand new, and there are some limitations to this - mainly, the builds have to be Maven-based. Soon any Jenkins build (and plugin) will be supported, but for now, Maven has to build it. The runtimes are currently only Tomcat or JBoss. Databases are limited to MySQL.
Chief Diversity Consultant
Michael is an open source polyglot developer. For his sins he spent time at JBoss, working on the Drools project, and then Red Hat, where he continually caused trouble on various projects. His interest in the cloud is natural, as he is attracted to disruptive technologies. Michael lives and works in the Blue Mountains, just outside Sydney, Australia.