Getting Started with Project "Piper"

Follow this guided tour to become familiar with the basics of using project "Piper".

Prerequisites

You have installed a Linux system with at least 4 GB memory. Note: We have tested our samples on Ubuntu 16.04. On Microsoft Windows, you might face some issues.
You have installed the newest version of Docker. See Docker Community Edition. Note: we have tested on Docker 18.09.6.
You have installed Jenkins 2.60.3 or higher. Note: If you use your own Jenkins installation you need to care for "Piper" specific configuration. Follow my own Jenkins installation. Recommendation: We recommend to use the cx-server toolkit. See (Optional) Install the cx-server Toolkit for Jenkins.
You have a GitHub account. See Signing up for a new GitHub account.
You have access to a repository on GitHub. See Creating a repository on GitHub.
You have an account and space in the Cloud Foundry environment on SAP Cloud Platform. See Get Started with a Trial Account: Workflow in the Cloud Foundry Environment.

(Optional) Install the `cx-server` Toolkit for Jenkins

cx-serveris a lifecycle management toolkit that provides Docker images with a preconfigured Jenkins and a Nexus-based cache to facilitate the configuration and usage of Jenkins.

To use the toolkit, get the cx-server script and its configuration file server.cfg by using the following command:

docker run -it --rm -u $(id -u):$(id -g) -v "${PWD}":/cx-server/mount/ ppiper/cx-server-companion:latest init-cx-server

When the files are downloaded into the current directory, launch the Jenkins server by using the following command:

./cx-server start

For more information on the Jenkins lifecycle management and how to customize your Jenkins, have a look at the Operations Guide for Cx Server.

Create Your First Pipeline

For the beginning, we recommend using an SAP sample application. The repository cloud-cf-helloworld-nodejs contains a simple nodejs application that can be enriched with a pipeline built with MTA and deployed into the Cloud Foundry environment.

Fork the cloud-cf-helloworld-nodejs repository into your GitHub organization.
Select the 1_REST_persist_in_Memory branch of your cloud-cf-helloworld-nodejs fork.
Create a new file with the name Jenkinsfile in the root level of your repository and enter the following code:
```
@Library('piper-lib-os') _
node() {
    stage('prepare') {
        checkout scm
        setupCommonPipelineEnvironment script:this
    }
}
```
The "prepare" step synchronizes the repository and initializes the project specific settings. For more information about Jenkinsfiles and pipelines, see Using a Jenkinsfile.
Save your changes to your remote repository.
To set up a Jenkins job for your repository, open the Jenkins UI under http://<jenkins-server-address>:<http-port> and choose New Item. Per default, the cx-server starts Jenkins on HTTP port 80. For more information, see the Jenkins User Documentation.

![Clicke New Item](../images/JenkinsHomeMenu-1.png "Jenkins Home Menu")
Provide a name for your new item (for example, My First Pipeline) and select Pipeline.

![Create Pipeline Job](../images/JenkinsNewItemPipeline-1.png "Jenkins New Item")
For Definition in the Pipeline options, choose Pipeline script from SCM.
For SCM, choose Git.
For Repository URL in the Repositories section, enter the URL of your Git repository, for example https://github.com/<your-org>/cloud-cf-helloworld-nodejs. Note: If your repository is protected, you must provide your credentials in the Credentials section.

![Create Pipeline Job](../images/JenkinsNewItemPipeline-2.png "Jenkins New Item")
For Branch Specifier in the Branches to build section, enter the branch name */1_REST_persist_in_Memory.
Choose Save.
To run your pipeline, choose Build Now in the job UI.

Add a Build Step

In your Jenkinsfile, add the following code snippet after stage("prepare") { ... }:
```
stage('build') {
    mtaBuild script: this
}
```
The mtaBuild step calls a build tool to build a multi-target application (MTA). The tool consumes an MTA descriptor that contains the metadata of all entities which comprise an application or are used by one during deployment or runtime, and the dependencies between them. For more information about MTAs, see sap.com.

Create the MTA descriptor file with the name mta.yaml in the root level of the repository. Insert the following code:

_schema-version: 2.1.0
ID: com.sap.piper.node.hello.world
version: 1.0.0
description: A Hello World sample application
provider: SAP Sample generator
modules:
  - name: piper.node.hello.world
    type: nodejs
    path: .

Configure the step to build an MTA for the Cloud Foundry environment. Create the configuration file .pipeline/config.yml relative to the root level of the repository and insert the following content:
```
general:
steps:
  mtaBuild:
    buildTarget: 'CF'
```
For additional information about the configuration, have a look at the Common Configuration Guide and the MTA build step documentation.
Save your changes to your remote repository.
To run your pipeline, choose Build Now in the job UI.

Add a Deploy Step

In your Jenkinsfile, add the following code snippet:

stage('deploy') {
    def mtarFilePath = commonPipelineEnvironment.getMtarFilePath()
    cloudFoundryDeploy( script: this, mtaPath: mtarFilePath)
}

The cloudFoundryDeploy step calls the Cloud Foundry command line client to deploy into SAP Cloud Platform.

To configure the step to deploy into the Cloud Foundry environment, in your repository, open or create the .pipeline/config.yml and add the following content:
```
cloudFoundryDeploy:
  deployTool: 'mtaDeployPlugin'
  deployType: 'standard'
  cloudFoundry:
    org: '<your-organisation>'
    space: '<your-space>'
    credentialsId: 'CF_CREDENTIALSID'
```
The key CF_CREDENTIALSID refers to a user-password credential you must create in Jenkins: In Jenkins, choose Credentials from the main menu and add a Username with Password entry.

![Add Credentials](../images/JenkinsCredentials-1.png "Add Credentials")
For more information about the configuration, see the [Common Configuration Guide][resources-configuration] and [cloudFoundryDeploy][resources-step-cloudFoundryDeploy].
Save your changes to your remote repository.
To run your pipeline, choose Build Now in the job UI.

Complete the Guided Tour

Your application has been deployed into your space in the Cloud Foundry space on SAP Cloud Platform. Logon to SAP Cloud Platform and verify the status of your application.

![Deployed Application](../images/SCPDeployApp-1.png "SAP Cloud Platform")

To view the URL of your application, choose the application name. Open the Route and add /users to the URL. Result: The application returns data.

If your pipeline fails, compare it to the final Jenkinsfile, the config.yml, and the mta.yaml. Yaml files are sensitive regarding indentation.

What's Next

You are now familiar with the basics of using project "Piper". Through the concept of pipeline as code, project "Piper" and Jenkins pipelines are extremely powerful. While Jenkins pipelines offer a full set of common programming features, project "Piper" adds SAP-specific flavors. Have a look at the increasing list of features you can implement through the project "Piper" steps and see the different scenarios to understand how to integrate SAP systems into your pipeline.

The configuration pattern supports simple pipelines that can be reused by multiple applications. To understand the principles of inheritance and customization, have a look at the the configuration documentation.

10 KiB Raw Blame History