Develop and deploy an application to a Virtual Machine

This tutorial demonstrates how to set up a Continuous Delivery toolchain and deliver a simple application (app) to a Virtual Machine. You can set up source control, and then build, test, and deploy the code to different deployment stages.

By default, the toolchain uses a sample Maven-based Java Hello World app, but you can also bring your own app and link to it instead. This toolchain is configured with pipelines for continuous integration and continuous delivery with Code Risk Analyzer, source control, issue tracking, and online editing.

The application code is stored in the application source control repository (repo). The build and deploy scripts are stored in the pipeline source control repository. You can customize the build and deploy scripts to meet the development requirements for the app.

The toolchain in this tutorial implements the following best practices:

Builds an application binary on every Git commit, and sets a tag based on build number, timestamp, and commit ID for traceability.
Inserts the built binary into the deployment manifest automatically.
Creates a Object Storage instance and Bucket to store the transient binary files that are built out-of-box. For advanced users, an existing Artifactory repo can be configured and integrated with the toolchain to support the versioning of build artifacts for traceability and compliance purposes.

The toolchain implements three pipelines to build and deploy app code to a Virtual Machine.

Continuous Integration (CI) Pipeline: This pipeline is triggered when a change is merged to the master branch of the Application Source Code repo. The CI Pipeline runs the Unit Test, Code Coverage, and Static Scans on the Application Source Code. The CI Pipeline also generates the binary build artifact and uploads it to the Object Storage Bucket or Artifactory, as configured in the toolchain. And the CI Pipeline generates the metadata of the build artifacts and stores it in the Inventory repo.
Continuous Deployment (CD) Pipeline: This pipeline is triggered by a successful CI Pipeline run. The CD Pipeline is responsible for deploying the build artifacts to the deployment environment. The pipeline verifies the successful deployment of the application by running the health check and rolls back the changes if the deployment is unsuccessful.
Pull Request (PR) Pipeline: This pipeline is triggered when a merge or pull request is created in the Application Source Code Repository. Typically, this request is manually created by the application source code developer to merge changes from their development branch to the master branch or any other branch. The PR Pipeline runs the Unit Test and Static Scans on the Application Source Code.

Before you begin

Set up and configure the Virtual Server Instance for the toolchain to deploy the app to the Virtual Server Instance. You can use an existing Virtual Server Instance or set up a new one that conforms to the following requirements:

Set up the Virtual Server Instance on IBM Cloud.
Reserve a floating IP address to make the Virtual Server Instance accessible over the public internet. Alternatively, you can use the available DNS entry. This tutorial uses a floating IP address.
Create the user (preferably non-privileged) and SSH keys for the Virtual Server Instance.
Configure Security Groups for the Virtual Server Instance. Enable the toolchain to perform health checks on the deployed app by adding an inbound rule for TCP to allow port 8080 so that it can access the app endpoint. For more information about adding an inbound rule, see Managing security groups.
Ensure that Java™ SDK is installed on your VM or use the following command to install it: yum install -y tar java.
Optional. If you need to store secrets in Key Protect, perform base64 encoding of the value. For more information about the required command details, see Image signing: generating a GPG key.

Create the toolchain

To create a Develop an application for a Virtual Machine toolchain, click

Alternatively, from the IBM Cloud console, click the Menu icon hamburger icon > Platform Automation > Toolchains. On the Toolchains page, click Create a Toolchain. On the Create a Toolchain page, click Develop an application for a Virtual Machine.

Configure the simple Virtual Server Instance

In the Create tab, review the default settings.

Toolchain settings
The toolchain's name identifies it in IBM Cloud. If you want to use a different name, change the toolchain's name. Because the toolchain name is used to construct the URL that is used to access your app, make sure to specify a unique name.
By default, the toolchain creates the source repo in Git Repos and Issue Tracking. To use a different provider for your Git source repo, such as GitHub or GitLab, select it from the list of available repos.

This toolchain uses tools that are included in the Continuous Delivery service. If an instance of that service isn't already in the selected resource group, it is added automatically with the free Lite plan when you click Create to create the toolchain.

Configure the App repo

In the Git Repos and Issue Tracking tab, review the default setting that specifies the location of your app's source code.
By default, the toolchain uses a sample Maven-based Java Hello World app. You can update the location setting to link to your own app instead.

App repo

Configure the Inventory repo

The Inventory Repository stores the metadata for builds and artifacts. To trigger the pipeline to deploy the artifacts that are described in the commit to the Virtual Server Instance, commit to the Inventory Repository, and then run the acceptance tasks.

Configure the Delivery Pipeline

Go to the Delivery Pipeline tab.

Delivery Pipeline configuration
Specify an existing IBM Cloud API Key or create a key. The toolchain uses this key to interact with other Cloud Services that are integrated into the toolchain.
Specify the region where the Virtual Server Instance is running, such as us-south.
Specify the floating IP address of the Virtual Server Instance by using the aaa.bbb.ccc.ddd format.
Select SSH Key Authentication Type and specify the following credentials:
- User Name: The username of the Virtual Server Instance user with permissions to deploy and run the application.
- SSH Key: The user's private SSH Key for running and deploying the application.

Run the following commands to create a new key-pair on the Virtual Server Instance for the user with permissions to deploy and run the applications.

        # Create the SSH key
            `ssh-keygen -C cloud.ibm.com`
        # copy public key to the VSI
            `ssh-copy-id -i .ssh/id_rsa.pub <UserName>@<xx.yy.zz.aa>`

Optional. Create transient storage configuration

Any change to the source triggers the continuous integration pipeline. When a continuous integration run succeeds, a build or binary artifact is created and saved in transient storage, and then deployed to the target Virtual Server Instance.

From the More Tools tab within your toolchain, you can choose to use either Object Storage or Artifactory as transient storage to save the build binary files.
If your account doesn’t contain any instances of Object Storage, the toolchain creates a new Object Storage instance in the default resource group. Next, the toolchain creates a bucket that uses the same name as the toolchain within the new Object Storage instance.
If your account already contains Object Storage instances, the toolchain uses one of those instances to store transient build artifacts.
To configure Object Storage or Artifactory details, see the Configuring advanced user options section.
Click Create to create the toolchain.

Explore your new toolchain

After you create your toolchain, it shows each of the tool integrations that are part of the toolchain in a diagram.

Explore the pipelines

You can explore the pipelines to understand the toolchain flow and the different operations that run within each pipeline. For example, to view multiple steps such as cra-discovery-scan and the details for Parameter and Status, click the CI Pipeline tool integration, and then click Succeeded PipelineRuns.

CI PipelineRun details — Continuous Integration PipelineRun details

Explore DevOps Insights

DevOps Insights aggregates data from your toolchain so that you can track and improve your end-to-end DevOps processes. View quality metrics, track build and deployment jobs, view policies and more.

If your code does not meet or exceed a policy, the deployment is halted, preventing risks from being released. You can use DevOps Insights as a safety net for your continuous delivery environment or as a way to implement and improve quality standards.

The following image shows the Quality Dashboard that provides quality data sets such as unit tests, code coverage, functional verification tests, and static security scans for each application.

Explore GitOps

GitOps is a set of practices and tools that puts Git at the center of the DevOps toolchain and as the source of truth for what to deploy on the Virtual Server Instance. With GitOps, developers and operators use familiar Git workflows to define, review, approve, and audit changes to their infrastructure and applications. Automated tools take care of synchronizing the live state of their targets with the wanted state that is described in Git.

By using the toolchain in this tutorial, you can control deployments to multiple environments by creating one branch for each environment. The following example workflow triggers a Continuous Delivery pipeline when a pull request or a commit is made to a specific branch of the Inventory repo.

Create a toolchain for Virtual Server Instance on IBM Cloud by providing details for the Virtual Server Instance such as the Application repo and Object Storage. Do not specify any details for the Inventory repo.
After the toolchain is created, from the Inventory repo create multiple branches such as Dev, Staging, and Prod.
Click the Continuous Delivery Pipeline and go to the triggers. Add a trigger source as an Inventory repo with the branch that you want to trigger the CD-Pipeline (Master).
Modify your Continuous Integration pipeline to commit to respective Inventory repos after successful integration.
After enough commits are available in the Inventory repo, merge the pull request in the repo to master to start a Continuous Delivery build.

By using GitOps, you can control deployments to multiple environments by creating one branch for each environment.

Configure advanced user options

To access the advanced user options, go to the More Tools tab.

Specify an existing Cloud Object Storage instance to store transient build artifacts:
- Specify the name of the bucket in your Object Storage instance where you want to store the transient build artifacts. To upload objects to the bucket, it must reside in the same region where the toolchain is created.
- Select the API Key that has read and write access to the bucket that you specified.
Cloud Object Storage integration details
To use an Artifactory account to store transient build artifacts, specify details for your Artifactory instance:
- Artifactory Server URL: HTTPS URL of the Artifactory Server
- Type: Choose from npm, maven, or docker
- Artifactory UserID: User ID to log in to the Artifactory Server, in the xxx.xxx@xxx.com format
- Artifactory APIKey: APIKey generated by the User (Existing or New)
- Release URL: Release URL for the Artifactory repo where artifacts are stored

Some fields in the Artifactory are mandatory only when you use the Artifactory configuration.

Artifactory Integration Details — Artifactory integration details

Click Create to create the toolchain. This process might take several minutes to complete.

Optional. Roll back to the previous version of the deployed application

You might want to roll back the deployed code because of test results, code quality issues, and other issues. You can use the Inventory Repository to roll back to the previous version of the application.

Type git clone <inventory-repo-url> to clone and download the Inventory Git repo from your pipeline. The Continuous Delivery pipeline listens to the master branch of the Inventory repo.
Type git log to view the list of commits completed by the Continuous Integration pipeline.
Type git checkout master to check out the master branch.
Type lastCommitID=$(git log --format="%H" -n 1) to retrieve the last commit ID for the repo.
Type git revert $lastCommitID to create a new commit by reverting the current change. Make sure that you provide a commit message for this revert.
Type git push to push the change to the Inventory repo and start the Continuous Delivery pipeline for application deployment.

Next steps

Although this tutorial used an example Java app, you can also deploy other language-based apps on a Virtual Server Instance. To deploy a different language-based app to a Virtual Server Instance, delete both the toolchain and the Virtual Server Instance that you created for this tutorial.