January 13, 2016 | Written by: Rolando Asmat
Share this post:
This blog references DevOps Services at hub.jazz.net, which has been deprecated. To get the latest tools for agile projects, use IBM Bluemix Continuous Delivery. For more information, see Share your code with the new Deploy to Bluemix button.
The Deploy to Bluemix button is a great way of getting users started with your sample application. In this blog, I will cover a brief introduction to deploying applications on Bluemix, how to create a Deploy to Bluemix button for your own application, and the steps that take place when a developer clicks on the button.
Quick review of applications in Bluemix
When you deploy an application to Bluemix, you have to keep in mind what is actually being deployed. For a mobile app, Bluemix builds and deploys an artifact that represents the mobile app’s backend. This is usually a server written in Node.js or Java. Along with the server, you can also instantiate and bind any Bluemix service from the catalog your application requires. The idea is to have your mobile application talk to this server and then have the server talk to the instantiated services. A Bluemix application is the combination of this server artifact, the collection of required services, and the mobile/web application.
The Deploy to Bluemix button makes it easy for new developers to get started with your application by automating the following:
- Creates a Bluemix application in the user’s account
- Instantiates all of the required services and binds them to the created application
- Deploys the server component on the user’s Bluemix account
- Creates a IBM Bluemix DevOps Services project on the user’s account with a clone of your repository’s master branch.
Steps to enable the one-click “Deploy to Bluemix” button
For the following instructions, we have the assumptions below:
- You have a public GitHub repository that has a README and the iOS mobile application source code
- You have a Bluemix application that uses a Node.js server and a number of Bluemix services. There is no compilation step for your server
- You wish to add a Deploy to Bluemix button to your README file.
We’ll use the BluePic iOS app as an example of how to create a button. This app uses four Bluemix services and has a Deploy to Bluemix button in its README for developers to use. Try it! You’ll see how one click on this button will handle everything.
There are three main components to get the Deploy to Bluemix button working:
Step 1: Place the button
The first component is the actual Deploy to Bluemix button in your README.md file. Use the following code snippet to create and place the button in your README file by replacing
YOUR_GIT_URL_HERE with your repository’s URL. Note: your Git repository must be public.
<a href="https://bluemix.net/deploy?repository=YOUR_GIT_URL_HERE"> <img src="https://bluemix.net/deploy/button.png" alt="Deploy to Bluemix"></a>
[![Deploy to Bluemix](https://bluemix.net/deploy/button.png)](https://bluemix.net/deploy?repository=YOUR_GIT_URL_HERE)
Your README should now have a button like this:
Step 2: Add and modify your manifest.yml file
A manifest.yml file placed at the root of the repository specifies which services the app needs. To begin, go to your Bluemix app’s Application Overview page:
Once you’re on this page, open the Start Coding tab and click Download Starter Code:
Unzip the folder and locate the manifest file:
manifest.yml with the following edits:
- Add a
declared-services field at the top of the file
- Copy and paste all the entries of
declared-services, each in its own line
- For each service under
declared-services add a
plan field. This information can be found by going to the Application Overview and opening the credentials section of each service entry. For example, this is where it would be for the Mobile Client Access service:
- Edit the
path field; it should point to the directory where your server component is located. For our example, the value should be
Once finished with the edits, ensure that this file is at the root of your repository. In the end, you should have something like this:
Step 3: Add the server files/folders
The third and final component is the server code that gets deployed to Bluemix. Create a
NodeStarterCode folder at the root of the repository. In it, paste all your Node.js server files/folders of your Bluemix Application.
That’s it! At this point your README should have a button for new developers to utilize!
Try your new “Deploy to Bluemix” button!
The following steps will take place once a developer clicks on the button:
- The master branch of the specified repository will be cloned into new private Bluemix DevOps Services project under the user’s account
- If a build file was provided, it will be automatically detected and executed. Our example used a server that didn’t require a compilation step so this step is not covered in this blog
- The manifest file is used to initialize/bind the required services and deploys the application to the user’s account.
Now you can create and put these buttons on any README or webpage desired!