How-tos

Enable existing projects for IBM Cloud with the IBM Cloud Developer Tools CLI

Share this post:

The IBM Cloud Developer Tools CLI (formerly referred to as the Bluemix CLI dev plugin) was recently promoted to 1.0, and is loaded with features that enable developer productivity. One of the most recent additions is the “enable” command. This feature is still in Beta, but we’re releasing it to you to gather feedback so that we can make it even better.

The enable command lets you take an existing server-side project and generate all of the assets needed to deploy it to the IBM Cloud. The Getting Started section below contains installation instructions.

How does it work?

Using the enable command is straightforward – open a terminal and navigate to your project’s root directory. Inside of that terminal invoke the enable command:

[code]bx dev enable[/code]

This action will first inspect the project to determine the primary language. The identified language will then be used to generate language-specific assets that will be utilized for deployment to IBM Cloud.

You can see a preview of this process in the video below:

The auto-detected language for a project is determined by the presence of valid configuration files for the server side project:

  • Package.swift in the project root identifies a Swift project
  • pom.xml in root identifies a Java project using the Maven starter**
  • build.gradle in root identifies a Java project using the Gradle starter**
  • requirements.txt or setup.py in the project root identifies a Python project
  • package.json in the project root identifies a Node.js project

** Java projects are further inspected to discover if the project will use Spring or Java Microprofile / EE.

You also have the ability to override the determined language using the –language command line argument in the event that multiple languages are detected or a language is incorrectly identified for the project.

Once a language has been specified, you will be prompted to specify a host name for the project on the IBM Cloud, and then the deployment assets will be downloaded and overlaid on top of the existing project. You’ll see a message similar to the following:

[code]The following files were added to your project:
Dockerfile
Dockerfile-tools
cli-config.yml
manifest.yml
.bluemix/deploy.json
.bluemix/pipeline.yml
.bluemix/toolchain.yml
chart/helloworld/Chart.yaml
chart/helloworld/values.yaml
chart/helloworld/templates/deployment.yaml
chart/helloworld/templates/service.yaml[/code]

OK, great, you now have a bunch of extra files, but what does this mean? Let’s take a closer look at those files…

Dockerfile / Dockerfile-tools

These are files that contain commands to create Docker images for both IBM Cloud deployment and running locally. “Dockerfile” is used to create the Docker image used for both local bx dev build/run and for remote bx dev deploy. “Dockerfile-tools” is used to create the Docker image used by bx dev debug for local debugging; this file contains additional configuration to aid in compiling and debugging.

cli-config.yml

This file is used by the IBM Development Tools CLI in all of the build/debug/run/stop/deploy operations. You can change default settings for these actions by modifying the “cli-config.yml” file. For example, you can change the default deployment from Cloud Foundry to Kubernetes, or change the default run/debug commands. You can learn more about the contents of the cli-config.yml file in the dev extension documentation.

manifest.yml

The Cloud Foundry manifest. This file describes the configuration for a CloudFoundry deployment and is utilized by a “cf push” command for deploying to Cloud Foundry environments, which is used by bx dev deploy when targeting Cloud Foundry environments.

.bluemix Files

The files inside of the “.bluemix” folder are templates that can be used to setup DevOps automation for building piplines and toolchains for IBM DevOps services for continuous delivery.

chart Files

The “chart” folder contains a Helm chart that describes the application deployment to Kubernetes environments. Helm charts are templatized manifests for Kubernetes deployment, and are most commonly organized in the folder structure of “chart/{application name}”. The helm chart is used by the bx dev deploy command when targeting Kubernetes environments, and can be customized to support complex or multi-container deployments. You can read more about the new Kubernetes support by the IBM Cloud Developer CLI here.


All of these files will be overlaid on top of the folder structure of your project relative to the root folder, and you’ll see a summary printed out at the end of the process which lists all of the files that have been added.

What if you already have some of these files and there are conflicts?

First and foremost, existing files and code are never overwritten. If your project already contains a file, the new file will be placed next to the existing file with the suffix “.merge” appended to the file name. If there are conflicts detected during the enablement process, then a list of conflicts will also be displayed at the end of the bx dev enable command.

For example: If your project already contains a file called “Dockerfile”, then the newly generated Dockerfile will be placed directly next to the existing file as “Dockerfile.merge”. You can inspect these files manually to merge them or use a file comparison tool such as “git diff Dockerfile Dockerfile.merge” to compare and merge them. Once the conflicted files are merged, you can safely remove the file with the “.merge” suffix.

Getting started

Getting started with the IBM Cloud Developer Tools CLI is easy. The first thing you need to do is install the Bluemix CLI and it’s dependencies using the single step installer for your OS.

If you’re on MacOS, just open up a terminal and run the following command:

[code]curl -sL https://ibm.biz/idt-installer | bash[/code]

If you’re on Windows 10, open Windows PowerShell by right-clicking and select “Run as Administrator” and run the following command:

[code]Set-ExecutionPolicy Unrestricted; iex(New-Object Net.WebClient).DownloadString(‘http://ibm.biz/idt-win-installer’)[/code]

This will install the all necessary dependencies if you don’t already have them installed. If you’re curious about what this installer is doing “under the covers”, you can check out the installation scripts at https://github.com/IBM-Bluemix/ibm-cloud-developer-tools

Troubleshooting

The Dockerfile and cli-config.yml files are created based on some assumptions of the project structure. For example, by default, a Node.js project assumes that the package.json file has scripts for “start”, “debug”, “test”, and other values. If you invoke a “bx dev debug” command on your newly enabled project, and the application fails to start, you probably want to look at the contents of your package.json to make sure it has a “debug” script, and/or compare it with the debug/run/stop command mappings within the cli-config.yml file.

Feedback

The enable feature is currently in Beta. We understand that not all projects are structured in the same way, and are working to make this feature as useful to you as possible. If you have any feedback, have suggestions for improvement, or run into any problems, please contact the development team on Slack at:
https://ibm-cloud-tech.slack.com/messages/C6NRG71A4/

More How-tos stories
October 15, 2018

Add Custom Domain and TLS Certificate to Your Secure Cloud App

Secure your cloud app end to end. Use a custom domain with TLS certificate for apps deployed on IBM Cloud Kubernetes Service.

Continue reading

October 12, 2018

Cloud Functions Package Design and Best Practices

Whether they're JARs, libs, Gems, or modules, successful programming languages provide an ability to share and re-use code. IBM Cloud Functions is no different—it enables developer productivity through installable packages. But what makes a good package?

Continue reading

October 5, 2018

Deploying a Microservices-Based Solution to Cloud Foundry Enterprise Environment (CFEE)

With Cloud Foundry Enterprise Environment (CFEE), you can instantiate multiple, isolated, enterprise-grade Cloud Foundry platforms on demand. Instances of the CFEE service run within your own account in IBM Cloud.

Continue reading