Tech Tip

Deploy Liberty application to Bluemix

Print

This lab shows how to use IBM UrbanCode Deploy (UCD) to deploy Liberty applications to Bluemix. This lab provides an introduction to IBM UrbanCode Deploy for those unfamiliar with it.

Prerequisites for this lab are:

  • Linux machine (requirements here) but 4GB RAM and 20GB disk is sufficient. Red Hat Linux 7 is recommended as it was the Linux version used in the lab. Ubuntu and other distros should work too but might require script modifications. Windows works too since UCD is available for Windows, but the scripts will not work.
  • Bluemix account (get it free).

UCD and other software will be installed during the setup of the lab.

The lab has following phases:

Liberty application in this lab is Daytrader application, available at GitHub

Setup

Part 1

Here we install UrbanCode Deploy, Maven and Bluemix CLI tools.

  1. Download UrbanCode Deploy from https://developer.ibm.com/urbancode/products/urbancode-deploy/. Click the “Free Trial” link and after logging in using your IBM ID you can download UCD.
  2. As of this writing, the latest UCD version is 6.2.4. Download that version, or newer one. The file name of UCD Server 6.2.4 trial is: URBANCODE_DEPLOY_V6.2.4_TRIAL_MP_.zip.
  3. If the UCD zip file is not already on Linux, copy/move it there.
  4. To install UCD, we use the install script available from GitHub.
    • Clone repo using: git clone –recursive https://github.com/samisalkosuo/scripts.
    • Install UCD server using: sh install_ucd.sh UCDSERVER_BINARY=/path/to/URBANCODE_DEPLOY_V6.2.4_TRIAL_MP_.zip
      • By default, the script installs JDK8, UCD and starts UCD server.
    • UCD server URL is: https://host.name.or.ip:8443/
      • User name is: admin.
      • Password is: passw0rd.
  5. We need to install Maven because we are going to build the Daytrader application using Maven.
    • Download Maven from: https://maven.apache.org/download.cgi
      • Latest version is 3.5.0 and the file name is apache-maven-3.5.0-bin.zip
      • For example, download using wget: wget http://www-eu.apache.org/dist/maven/maven-3/3.5.0/binaries/apache-maven-3.5.0-bin.zip
  6. Unzip Maven to any directory in Linux. Remember the directory because it’s needed later when we use UCD Maven build plug-in.
  7. We also need Cloud Foundry CLI tools to interact with Bluemix. For that, we install Bluemix CLI tools.
    • Install Bluemix CLI tools by executing the sh setup_bluemix_cli.sh script that is available in the same GitHub repo as the previously used install_ucd.sh script (also installs kubectl and docker).
    • Alternatively, go to: https://clis.ng.bluemix.net/ui/home.html and follow the instructions.
  8. That’s it. UCD, Maven and Bluemix CLI tools are now installed and the next step is to setup UCD for our purpose.

Part 2

Here we install necessary plug-ins to UCD in order to use Maven build, and to deploy to Bluemix.

  1. Login to UCD. The UCD server URL is: https://host.name.or.ip:8443/ and welcome screen opens. UCD Welcome screen
  2. In order to install new plug-ins go to “Settings” -> “Automation plugins”.
  3. The screen lists all the plug-ins UCD includes. There’s “Load plugin”-button that you can use to add new plug-ins.
  4. There is Maven plug-in for UCD.

  5. The Cloud Foundry plug-in is also available. Download it from https://developer.ibm.com/urbancode/plugin/cloud-foundry/ and load it.

That’s the setup we need now. Next, we create UCD components, processes, and other resources to deploy the application to Bluemix.

Create UCD resources

Now that UCD server is set up, we are ready to go and we follow the modeling software deployment workflow as described in UCD Knowledge Center.

Daytrader component

  1. Go to Components tab.
  2. Press “Create Component” and enter following values:
    • Name: Daytrader7
    • Source configuration type: Git
    • Repository URL: https://github.com/samisalkosuo/sample.daytrader7
    • Branch: master

    Create component

  3. Press “Save” and Component screen opens. Component screen
  4. First, we need to import the latest version. Press “Versions” and then click “Import New Versions”. Click “Save” to start import (optionally, enter your own version string as “Name to create version with”).
  5. Press “Refresh” after a couple of seconds and you will see the new version. Component version
  6. Now that we have a version, let’s create a component processes. Component processes are tasks related to the component, in this case Daytrader. Typical processes include installation, uninstallation, modification and so on. For the Daytrader7 component we create three processes: Download artifacts, Deploy Daytrader and (optionally) Destroy Daytrader.
  7. Click “Processes” tab and click “Create Process”.
    • Enter “Download artifacts” as name.
    • Leave the other parameters with default values.
    • Click”Save”
  8. Process designer screen opens. Component process designer
    • The large canvas is where the process is visible.
    • On the left, the palette shows a list of all the steps that are available for the process.
    • The configuration tab shows component configuration including component properties.
  9. The download artifacts process is very simple. There is just one step called “Download artifacts”. Find it on the palette and drag it to the canvas. Component process designer

    • Click the pen-icon on the Download artifacts step to see the step properties. Leave them as they are and click “OK”.
    • Click “Save” and the process is saved.
    • This Download artifacts process includes only download artifacts step. Having this step might be helpful during development because you might change the component and you might want to test it manually on target systems. By calling this Download artifacts process, component files are downloaded and nothing else is done.
  10. The next process is “Deploy Daytrader”. Create the process with that name.
  11. The first step in the Deploy-process is to download artifacts. Find “Run Component Process” step in the palette under Utility steps drag it to canvas. Click the Pen-icon and enter the name “Download artifacts” and select “Download artifacts” component process.Download artifacts step
    • This is how you can call other component processes and reuse them.
  12. Click “OK”.
  13. Find “Maven Build” step in the palete and drag it to canvas. Reorder the steps so that “Maven Build” happens after “Download artifacts”. Maven build step
  14. Click the pen-icon of the Maven build component and enter following values:
    • Goals: install.
    • Mave home: path to Maven-directory.
    • Maven version: 3.3.0 and above. Maven build properties
    • Press “OK” and click “Save” to save the process.
  15. Typically, creating these processes is an iterative process and this deploy process is already something we could test in a real environment. You could run this process for real and check the results. However, in the context of this lab, we create the complete process and test later.
  16. After the Maven build step, we are going to package Liberty Daytrader application as a zip-file. For this, we use the server command of Liberty and Shell step of the UCD process.
  17. Find the Shell step in palette and drag it to canvas. Shell step
  18. Press the pen-icon of Shell step and enter following values:
    • Name: Package app.
    • Shell script:
      #Package Daytrader app as zip
      #includes also Derby libs
      export WLP_USER_DIR=$(pwd)/daytrader-ee7-wlpcfg
      ./daytrader-ee7/target/liberty/wlp/bin/server package daytrader7Sample --include=usr
      
      #move daytrader app zip file to root of working dir, for easier access later
      mv daytrader-ee7-wlpcfg/servers/daytrader7Sample/daytrader7Sample.zip .
      
    • Shell-step can include any shell-script. This opens nearly limitless possibilities what can be done during UCD processes.
    • Press “OK”.
  19. The final step of Deploy Daytrader process is to deploy application to Bluemix. For that, we use a step found in Cloud Foundry plug-in.
    • Find the Push application step from the palette and drag it to canvas.
    • Click the pen-icon and enter these values:
      • Name: Push application.
      • Application name: unique name of app, include your initials or datetime etc.
      • Application path: daytrader7Sample.zip (this was created in previous step and moved to the working directory).
    • Note how Cloud Foundry/Bluemix properties show values like ${p:resource/cf.api}. These refer to resource properties and will be defined later.
    • Click “Save”.
  20. The Daytrader component is now ready and the next step is to create the application and resources so that we can deploy Daytrader to Bluemix.

Daytrader resource

A resource in UCD is typically a target environment like a server, or collection of servers where the application and components are going to be deployed.

A resource has at least one agent that is responsible for executing processes like the Daytrader processes we created earlier.

In this lab, we create a resource representing Bluemix US South.

  1. Click “Resources” on top of the UCD menu.
  2. Click “Create Top-Level Group” and enter name: Bluemix US South. Top-level resource
  3. Click “Save”.
  4. Hover your mouse over the created resource and select “Actions” -> “Add agent”.
  5. Select the only available agent “ucd-agent-local”. Add agent
  6. Click “Save”. This ties the UCD agent to the resource. In our case, the local agent is used to execute processes. You could also have agents in another machines. If processes include some heavy build processes or there is potentially many processes at the same time, it is recommended to have a separate worker machine and not use the UCD server.
  7. In earlier step there were references to resource properties. We add those properties now. Click the “Bluemix US South” resource (with folder-like icon). Then select “Configuration” and then “Resource properties”.
  8. Add the following Bluemix properties as resource properties (click “Add Property” and enter name and value):
    • cf.api: https://api.ng.bluemix.net
    • cf.org: your Bluemix organization
    • cf.password: your Bluemix password
    • cf.space: your Bluemix space
    • cf.username: your Bluemix username Resource properties

Now our Bluemix US South resource includes properties. Daytrader7-component process references these properties whenever process is executed in this resource.

The next step is to create Daytrader application. An application in UCD holds all the components that make up the application. For example, an application could have static web components, batch jobs, and so on. Applications are then tied to one or more environments (such as dev, test, and production) and each environment uses resources, like Bluemix US South that we just created.

Daytrader application

Applications are in the heart of UCD as they tie together components, resources, and environments. Applications include also application-level processes like install, update or uninstall. There is a limited set of steps in the application processes and the purpose of application processes is to coordinate components and call component processes in the correct order.

  1. To create the application, go to “Applications” and click “Create application”. Enter the name: Daytrader. Create application
  2. Click “Create”.
  3. The application screen opens and large text “No environments found!” is shown.
  4. Click “Create Environment” to create a new environment.
  5. Enter the name, for example: Test – Bluemix US South. Optionally, select a color. Create environment
  6. Click “Save”.
  7. Applications in UCD do nothing without components. Click “Components” and “Add Component” to include the only component we have in this server. Add component
  8. Click “Save”.
  9. Now that we have component, let’s go back to Environments. Click the environment name and Environment screen opens.
  10. Click “Add Base Resources”. Here we add our resource that we created earlier. Select the resource. Add base resource
  11. Click “OK”.
  12. Hover your mouse over the agent under the resource name and click “Actions” -> “Add Component”. Select the only component we have added to application: Daytrader7.
  13. Click “Save”. We now have an environment and a component. The next step is to create an application process to deploy Daytrader to Bluemix.
  14. In the Daytrader-application screen, click “Processes” and “Create Process”. Enter the name: Deploy. Create process
  15. Click “Save” and process designer screen opens.
  16. Note that the palette on the left does not show many steps. This is because application processes call processes defined in components. Components processes do the main work and application processes coordinate execution of component processes.

  17. Drag “Install Component” from the palette to canvas and click the pen-icon. By default, the Deploy Daytrader process of the Daytrader7 component should already be selected. Install component step
  18. Click “OK” and “Save”.

Now we have an application and a deployment process. Earlier we setup resources and components and the application is now ready for deployment.

Deployment

Now that we have everything ready, we can deploy the application.

  1. Go to “Applications” -> “Daytrader”
  2. The Application screen with environments opens.
  3. Click the Play button on the left-side of environment.
    • Deploy-process should be already selected.
    • Click “Choose Versions”. Here you select which component versions you want to include.
    • In the Dropdown menu “Select for all”, select “Latest available” and click “OK”. Run process
  4. Note the checkbox “Only Changed Versions”. If this is checked, and the application is already deployed and you have not changed the component version, nothing is done. Uncheck this to execute the process regardless whether or not the version changed.

  5. Click “Submit” to start process. The process request starts and the request screen is shown. Here you can see the execution and also view log files in case something goes wrong.
  6. After a few moments, the process is finished and you see the results. Process request

  7. In order to verify the deployment, go to your Bluemix account and see if the application is listed there. Bluemix apps
  8. If you click on the daytrader link, you probably see the “Not found” error message because the context root of the application is “/daytrader” and not “/”. Add “/Daytrader” to link and you see the Daytrader welcome screen.
    Daytrader welcome screen

And we are done. We used UrbanCode Deploy to deploy an application to Bluemix and learned about the main concepts of UCD.

  • There is much more to UCD than is described here. UCD is enterprise-grade tool including users, groups, authorizations, audit logs, highly scalable installations, etc. etc.
  • The main task of UCD is to automate deployments and here we have seen how that can be done.

Next, there are optional tasks to improve the processes.

Improvement

This part is optional and shows how to improve existing processes and so improve the user experience. The user might be a developer or tester who needs to deploy applications to Bluemix.

There are two obvious drawbacks in the current Daytrader processes. The first is that there is no way to delete applications (no destroy process) and the second is that Daytrader is not configured (you need to populate database manually before logging into the application).

Destroy process

Let’s create destroy app process first.

  1. Go to “Components” -> “Daytrader” -> “Processes” and click “Create Process”.
  2. Enter:
    • Name: Destroy Daytrader
    • Type: Uninstall Create process
  3. Click “Save”.
  4. Find the “Delete App” step on the palette and drag it to canvas.
  5. Enter your unique application name, for example: “daytrader7-ucd-sjs”. Edit properties
  6. Click “OK”.
  7. Click “Save” to save the process.
  8. Go to “Application” -> “Daytrader” -> “Processes” and click “Create process”.
  9. Enter the name: “Destroy”.
  10. Click “Save”.
  11. Drag “Uninstall Component” step from palette to the canvas and click the pen-icon to edit properties.
  12. All values should be already filled, but change “Component process” to Destroy Daytrader. Edit properties
  13. Click “OK” and “Save”.
  14. Test the process by going to Daytrader application and executing the process against the environment. If successful, the Daytrader application is removed from your Bluemix space.

Configure Daytrader

By default, the Daytrader application is not configured after deployment. It would better for users if Daytrader is configured during deployment. So, let’s change the deployment process.

  1. Go to “Deploy Daytrader” process of Daytrader7-component.
  2. Add a new shell-step and rename it to “Configure app,” and add the following script to it (remember to change the app name in DAYTRADER_URL):
    echo "Sleeping..."
    #sleep 30 seconds to allow app to start, just in case
    sleep 30
    echo "Sleeping done."
    
    #Configure Daytrader7 app
    DAYTRADER_URL=https://daytrader7-ucd-sjs.mybluemix.net/daytrader
    
    echo "Creating tables..."
    #(re)create all tables
    curl ${DAYTRADER_URL}/config?action=buildDBTables
    
    #Configure Daytrader 
    echo "Configuring..."
    curl -X POST --data 'action=updateConfig&RunTimeMode=0&OrderProcessingMode=0&WebInterface=0&MaxUsers=50&MaxQuotes=200&marketSummaryInterval=20&primIterations=1&EnablePublishQuotePriceChange=on&percentSentToWebsocket=10&DisplayOrderAlerts=on&EnableLongRun=on'  ${DAYTRADER_URL}/config
    
    #populate database
    echo "Populating database..."
    curl ${DAYTRADER_URL}/config?action=buildDB
    
  3. Add a new “Configure app” step to end of the process.
    Configure step
  4. Click “Save.”
  5. Test the new process by deploying the application and trying to login to the Daytrader application. If your login is successful, then the configuration step was successful.

There are many ways to further improve the application. For example, the application name could be an environment property.

Summary

This lab started with installation and configuration of IBM UrbanCode Deploy. Then component, application, and processes were created before deploying the application to Bluemix. Improving the processes reminds that work is iterative and can be improved to better serve the users.

By starting from scratch, from UCD installation, this lab provided a good introduction to what UCD is and what can be done with it.