jenkins/sap-jenkins-library
1
0
Fork 0
mirror of https://github.com/SAP/jenkins-library.git synced 2025-03-03 15:02:35 +02:00
Code Issues Releases Activity

Streamline documentation to reflect project "piper" (#875)

Browse Source
This commit is contained in:
Florian Wilhelm 2019-09-19 14:17:41 +02:00 committed by GitHub
parent 68758d1073
commit e041f45183
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 178 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
documentation/docs/configuration.md
View File

@ -1,6 +1,9 @@
# Configuration
Configuration is done via a yml-file, located at `.pipeline/config.yml` in the **master branch** of your source code repository.
Configure your project through a yml-file, which is located at `.pipeline/config.yml` in the **master branch** of your source code repository.
!!! note "Cloud SDK Pipeline"
Cloud SDK Pipelines are configured in a file called `pipeline_config.yml`. See [SAP Cloud SDK Pipeline Configuration Docs](https://github.com/SAP/cloud-s4-sdk-pipeline/blob/master/configuration.md).
Your configuration inherits from the default configuration located at [https://github.com/SAP/jenkins-library/blob/master/resources/default_pipeline_environment.yml](https://github.com/SAP/jenkins-library/blob/master/resources/default_pipeline_environment.yml).

9
documentation/docs/extensibility.md
View File

@ -4,10 +4,13 @@ There are several possibilities for extensibility besides the **[very powerful c
## 1. Stage Exits
You have to create a file like `<StageName>.groovy` for example `Acceptance.groovy` and store it in folder `.pipeline/extensions/` in your source code repository.
You have to create a file like `<StageName>.groovy` (for example, `Acceptance.groovy`) and store it in folder `.pipeline/extensions/` in your source code repository.
The pipeline template will check if such a file exists and executes it if present.
A parameter is passed to the extension containing following keys:
!!! note "Cloud SDK Pipeline"
If you use the Cloud SDK Pipeline, the folder is named `pipeline/extensions/` (without the dot). For more information, please refer to [the Cloud SDK Pipeline documentation](https://github.com/SAP/cloud-s4-sdk-pipeline/blob/master/doc/pipeline/extensibility.md).
The pipeline template checks if such a file exists and executes it, if present.
A parameter that contains the following keys is passed to the extension:
* `script`: defines the global script environment of the Jenkinsfile run. This makes sure that the correct configuration environment can be passed to project "Piper" steps and also allows access to for example the `commonPipelineEnvironment`.
* `originalStage`: this will allow you to execute the "original" stage at any place in your script. If omitting a call to `originalStage()` only your code will be executed instead.

31
documentation/docs/guidedtour.md
View File

@ -12,29 +12,46 @@ The stated instructions assume the use of this application.
* 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](https://docs.docker.com/install/). **Note:** we have tested on Docker 18.09.6.
* You have installed Jenkins 2.60.3 or higher. **Recommendation:** We recommend to use the `cx-server` toolkit. See **(Optional) Install the `cx-server` Toolkit for Jenkins**. **Note:** If you use your **own Jenkins installation** you need to care for "Piper" specific configuration. Follow [my own Jenkins installation][guidedtour-my-own-jenkins].
* Your system has access to [GitHub.com][github].
## (Optional) Install the `cx-server` Toolkit for Jenkins
## **Recommended:** Install the Cx Server Life-cycle Management for Jenkins
`cx-server`is 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.
Cx Server is a life-cycle management tool to bootstrap a pre-configured Jenkins instance within minutes.
All required plugins and shared libraries are included automatically.
It is based on Docker images provided by project "Piper".
To use the toolkit, get the `cx-server` script and its configuration file `server.cfg` by using the following command:
To get started, initialize Cx Server by using this `docker run` command:
```sh
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:
This creates a few files in your current working directory.
The shell script `cx-server` and the configuration file `server.cfg` are of special interest.
Now, you can start the Jenkins server by using the following command:
```sh
chmod +x ./cx-server
./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][devops-docker-images-cxs-guide].
For more information on the Cx Server and how to customize your Jenkins, have a look at the [Operations Guide for Cx Server][devops-docker-images-cxs-guide].
### On your own: Custom Jenkins Setup
If you use your own Jenkins installation, you need to care for the configuration that is specific to project "Piper".
This option should only be considered if you know why you need it, otherwise using the Cx Server life-cycle management makes your life much easier.
If you choose to go this path, follow [my own Jenkins installation][guidedtour-my-own-jenkins] for some hints.
**Note:** This option is not supported for SAP Cloud SDK projects.
## (Optional) Sample Application
!!! info "Choosing the best sample application"
Depending on the type of project you're interested in, different sample applications might be interesting.
For SAP Cloud SDK, please have a look at the [Address Manager](https://github.com/sap/cloud-s4-sdk-book) example application.
Copy the sources of the application into your own Git repository. While we will ask you to fork the application's repository into a **GitHub** space, you can use any version control system based on Git like **GitLab** or **plain git**. **Note:** A `public` GitHub repository is visible to the public. The configuration files may contain data you don't want to expose, so use a `private` repository.
1. Create an organization on GitHub, if you haven't any yet. See [Creating a new organization][github-create-org].
@ -189,7 +206,7 @@ Please also consult the blog post on setting up [Continuous Delivery for S/4HANA
[sap-blog-s4-sdk-first-steps]: https://blogs.sap.com/2017/05/10/first-steps-with-sap-s4hana-cloud-sdk/
[sap-blog-ci-cd]: https://blogs.sap.com/2017/09/20/continuous-integration-and-delivery/
[devops-docker-images-cxs-guide]: https://github.com/SAP/devops-docker-images/blob/master/docs/operations/cx-server-operations-guide.md
[devops-docker-images-cxs-guide]: https://github.com/SAP/devops-docker-cx-server/blob/master/docs/operations/cx-server-operations-guide.md
[cloud-cf-helloworld-nodejs]: https://github.com/SAP/cloud-cf-helloworld-nodejs
[github]: https://github.com

BIN
documentation/docs/images/cloud-sdk-pipeline.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 79 KiB

BIN
documentation/docs/images/webide-pipeline-template.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 127 KiB

49
documentation/docs/index.md
View File

@ -1,32 +1,45 @@
# Project "Piper" User Documentation
An efficient software development process is vital for success in building
business applications on SAP Cloud Platform or SAP on-premise platforms. SAP
addresses this need for efficiency with project "Piper". The goal of project
"Piper" is to substantially ease setting up continuous delivery processes for
the most important SAP technologies by means of Jenkins pipelines.
Continuous delivery is a method to develop software with short feedback cycles.
It is applicable to projects both for SAP Cloud Platform and SAP on-premise platforms.
SAP implements tooling for continuous delivery in project "Piper".
The goal of project "Piper" is to substantially ease setting up continuous delivery in your project using SAP technologies.
## What you get
Project "Piper" consists of two parts:
To get you started quickly, project "Piper" offers you the following artifacts:
* [A shared library][piper-library] containing steps and utilities that are
required by Jenkins pipelines.
* A set of [Docker images][devops-docker-images] used in the piper library to implement best practices.
* A set of ready-made Continuous Delivery pipelines for direct use in your project
* [General Purpose Pipeline](stages/introduction/)
* [SAP Cloud SDK Pipeline][cloud-sdk-pipeline]
* [A shared library][piper-library] that contains reusable step implementations, which enable you to customize our preconfigured pipelines, or to even build your own customized ones
* A set of [Docker images][devops-docker-images] to setup a CI/CD environment in minutes using sophisticated life-cycle management
The shared library contains all the necessary steps to run our best practice
Jenkins pipelines described in the Scenarios section or
to run a [pipeline as step][piper-library-scenario].
To find out which offering is right for you, we recommend to look at the ready-made pipelines first.
In many cases, they should satisfy your requirements, and if this is the case, you don't need to build your own pipeline.
The best practice pipelines are based on the general concepts of [Jenkins 2.0
Pipelines as Code][jenkins-doc-pipelines]. With that you have the power of the
Jenkins community at hand to optimize your pipelines.
### The best-practice way: Ready-made pipelines
**Are you building a standalone SAP Cloud Platform application?<br>**
Then continue reading about our [general purpose pipeline](stages/introduction/), which supports various technologies and programming languages.
**Are you building an application with the SAP Cloud SDK and/or SAP Cloud Application Programming Model?<br>**
Then we can offer you a [pipeline specifically tailored to SAP Cloud SDK and SAP Cloud Application Programming Model applications][cloud-sdk-pipeline]
### The do-it-yourself way: Build with Library
The shared library contains building blocks for your own pipeline, following our best practice Jenkins pipelines described in the Scenarios section.
The best practice pipelines are based on the general concepts of [Pipelines as Code, as introduced in Jenkins 2][jenkins-doc-pipelines].
With that you have the power of the Jenkins community at hand to optimize your pipelines.
You can run the best practice Jenkins pipelines out of the box, take them as a
starting point for project-specific adaptations or implement your own pipelines
from scratch using the shared library.
## Extensibility
For an example, you might want to check out our ["Build and Deploy SAPUI5 or SAP Fiori Applications on SAP Cloud Platform with Jenkins" scenario][piper-library-scenario].
#### Extensibility
If you consider adding additional capabilities to your `Jenkinsfile`, consult
the [Jenkins Pipeline Steps Reference][jenkins-doc-steps]. There, you get an
@ -41,7 +54,7 @@ Custom library steps can be added using a custom library according to the
groovy coding to the `Jenkinsfile`. Your custom library can coexist next to the
provided pipeline library.
## API
#### API
All steps (`vars` and `resources` directory) are intended to be used by Pipelines and are considered API.
All the classes / groovy-scripts contained in the `src` folder are by default not part of
@ -49,8 +62,10 @@ the API and are subjected to change without prior notice. Types and methods anno
`@API` are considered to be API, used e.g. from other shared libraries. Changes to those
methods/types needs to be announced, discussed and agreed.
[github]: https://github.com
[piper-library]: https://github.com/SAP/jenkins-library
[cloud-sdk-pipeline]: pipelines/cloud-sdk/introduction/
[devops-docker-images]: https://github.com/SAP/devops-docker-images
[devops-docker-images-issues]: https://github.com/SAP/devops-docker-images/issues
[devops-docker-images-cxs-guide]: https://github.com/SAP/devops-docker-images/blob/master/docs/operations/cx-server-operations-guide.md

41
documentation/docs/pipelines/cloud-sdk/introduction.md Normal file
View File

@ -0,0 +1,41 @@
# SAP Cloud SDK Pipeline
<img src="https://help.sap.com/doc/6c02295dfa8f47cf9c08a19f2e172901/1.0/en-US/logo-for-cd.svg" alt="SAP Cloud SDK for Continuous Delivery Logo" height="122.92" width="226.773" align="right"/></a>
If you are building an application with [SAP Cloud SDK](https://community.sap.com/topics/cloud-sdk), the [SAP Cloud SDK pipeline](https://github.com/SAP/cloud-s4-sdk-pipeline) helps you to quickly build and deliver your app in high quality.
Thanks to highly streamlined components, setting up and delivering your first project will just take minutes.
## Qualities and Pipeline Features
The SAP Cloud SDK pipeline is based on project "piper" and offers unique features for assuring that your SAP Cloud SDK based application fulfills highest quality standards.
In conjunction with the SAP Cloud SDK libraries, the pipeline helps you to implement and automatically assure application qualities, for example:
* Functional correctness via:
* Backend and frontend unit tests
* Backend and frontend integration tests
* User acceptance testing via headless browser end-to-end tests
* Non-functional qualities via:
* Dynamic resilience checks
* Performance tests based on *Gatling* or *JMeter*
* Code Security scans based on *Checkmarx* and *Fortify*
* Dependency vulnerability scans based on *Whitesource*
* IP compliance scan based on *Whitesource*
* Zero-downtime deployment
* Proper logging of application errors
![Screenshot of SAP Cloud SDK Pipeline](../../images/cloud-sdk-pipeline.png)
## Supported Project Types
The pipeline supports the following types of projects:
* Java projects based on the [SAP Cloud SDK Archetypes](https://mvnrepository.com/artifact/com.sap.cloud.sdk.archetypes).
* JavaScript projects based on the [SAP Cloud SDK JavaScript Scaffolding](https://github.com/SAP/cloud-s4-sdk-examples/tree/scaffolding-js).
* TypeScript projects based on the [SAP Cloud SDK TypeScript Scaffolding](https://github.com/SAP/cloud-s4-sdk-examples/tree/scaffolding-ts).
* SAP Cloud Application Programming Model (CAP) projects based on the _SAP Cloud Platform Business Application_ WebIDE Template.
You can find more details about the supported project types and build tools in the [project documentation](https://github.com/SAP/cloud-s4-sdk-pipeline/blob/master/doc/pipeline/build-tools.md).
## Legal Notes
Note: This license of this repository does not apply to the SAP Cloud SDK for Continuous Delivery Logo referenced in this page

54
documentation/docs/scenarios/CAP_Scenario.md
View File

@ -1,9 +1,49 @@
# Build and Deploy Applications with Jenkins and the SAP Cloud Application Programming Model
# Build and Deploy SAP Cloud Application Programming Model Applications
Set up a basic continuous delivery process for developing applications according to the SAP Cloud Application Programming Model. If you're building extensions of SAP solutions such as SAP S/4HANA, consider using [SAP Cloud SDK](https://developers.sap.com/topics/cloud-sdk.html) and [SAP Cloud SDK Pipeline](https://github.com/SAP/cloud-s4-sdk-pipeline) which provides an out-of-the-box continuous delivery pipeline based on project "Piper".
In this scenario, we will setup a CI/CD Pipeline for a SAP Cloud Application Programming Model (CAP) project, which is based on the _SAP Cloud Platform Business Application_ WebIDE Template.
## Prerequisites
* You have an account on SAP Cloud Platform in the Cloud Foundry environment. See [Accounts](https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/8ed4a705efa0431b910056c0acdbf377.html).
* You have setup a suitable Jenkins instance as described in [Guided Tour](../guidedtour.md)
## Context
The Application Programming Model for SAP Cloud Platform is an end-to-end best practice guide for developing applications on SAP Cloud Platform and provides a supportive set of APIs, languages, and libraries.
For more information about the SAP Cloud Application Programming Model, see [Working with the SAP Cloud Application Programming Model](https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/00823f91779d4d42aa29a498e0535cdf.html).
## Getting started
To get started, generate a project in SAP Web IDE based on the _SAP Cloud Platform Business Application_ template.
Make sure to check the Include support for continuous delivery pipeline of SAP Cloud SDK checkbox, as in this screenshot:
![WebIDE project wizard](../images/webide-pipeline-template.png)
This will generate a project which already includes a `Jenkinsfile`, and a `pipeline_config.yml` file.
In case you already created your project without this option, you'll need to copy and paste two files into the root directory of your project, and commit them to your git repository:
* [`Jenkinsfile`](https://github.com/SAP/cloud-s4-sdk-pipeline/blob/master/archetype-resources/Jenkinsfile)
* [`pipeline_config.yml`](https://github.com/SAP/cloud-s4-sdk-pipeline/blob/master/archetype-resources/cf-pipeline_config.yml)
* Note: The file must be named `pipeline_config.yml`, despite the different name of the file template
!!! note "Using the right project structure"
This only applies to projects created based on the _SAP Cloud Platform Business Application_ template after September 6th 2019. They must comply with the structure which is described [here](https://github.com/SAP/cloud-s4-sdk-pipeline/blob/master/doc/pipeline/build-tools.md#sap-cloud-application-programming-model--mta).
If your project uses SAP HANA containers (HDI), you'll need to configure `createHdiContainer` and `cloudFoundry` in the `backendIntegrationTests` stage in your `pipeline_config.yml` file as documented [here](https://github.com/SAP/cloud-s4-sdk-pipeline/blob/master/configuration.md#backendintegrationtests)
Now, you'll need to push the code to a git repository.
This is required because the pipeline gets your code via git.
This might be GitHub, or any other cloud or on-premise git solution you have in your company.
Be sure to configure the [`productionDeployment `](https://github.com/SAP/cloud-s4-sdk-pipeline/blob/master/configuration.md#productiondeployment) stage so your changes are deployed to SAP Cloud Platform automatically.
## Legacy documentation
If your project is not based on the _SAP Cloud Platform Business Application_ WebIDE template, you could either migrate your code to comply with the structure which is described [here](https://github.com/SAP/cloud-s4-sdk-pipeline/blob/master/doc/pipeline/build-tools.md#sap-cloud-application-programming-model--mta), or you can use a self built pipeline, as described in this section.
### Prerequisites
* You have an account on SAP Cloud Platform in the Cloud Foundry environment. See [Accounts](https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/8ed4a705efa0431b910056c0acdbf377.html).
* You have downloaded and installed the Cloud Foundry command line interface (CLI). See [Download and Install the Cloud Foundry Command Line Interface](https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/afc3f643ec6942a283daad6cdf1b4936.html).
* You have installed the multi-target application plug-in for the Cloud Foundry command line interface. See [Install the Multi-Target Application Plug-in in the Cloud Foundry Environment](https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/27f3af39c2584d4ea8c15ba8c282fd75.html).
@ -13,15 +53,15 @@ Set up a basic continuous delivery process for developing applications according
* You have installed the Multi-Target Application (MTA) Archive Builder 1.0.6 or newer. See [SAP Development Tools](https://tools.hana.ondemand.com/#cloud).
* You have installed Node.js including node and npm. See [Node.js](https://nodejs.org/en/download/).
## Context
### Context
The Application Programming Model for SAP Cloud Platform is an end-to-end best practice guide for developing applications on SAP Cloud Platform and provides a supportive set of APIs, languages, and libraries. For more information about the SAP Cloud Application Programming Model, see [Working with the SAP Cloud Application Programming Model](https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/00823f91779d4d42aa29a498e0535cdf.html).
In this scenario, we want to show how to implement a basic continuous delivery process for developing applications according to this programming model with the help of project "Piper" on Jenkins. This basic scenario can be adapted and enriched according to your specific needs.
## Example
### Example
### Jenkinsfile
#### Jenkinsfile
```groovy
@Library('piper-library-os') _
@ -43,7 +83,7 @@ node(){
}
```
### Configuration (`.pipeline/config.yml`)
#### Configuration (`.pipeline/config.yml`)
```yaml
steps:
@ -57,7 +97,7 @@ steps:
space: '<CF Space>'
```
### Parameters
#### Parameters
For the detailed description of the relevant parameters, see:

47
documentation/mkdocs.yml
View File

@ -1,8 +1,31 @@
site_name: Jenkins 2.0 Pipelines
site_name: 'Project "Piper": Continuous Delivery for the SAP Ecosystem'
nav:
- Home: index.md
- 'Guided Tour' : guidedtour.md
- Configuration: configuration.md
- 'Pipelines':
- 'General purpose pipeline':
- 'Introduction': stages/introduction.md
- 'Examples': stages/examples.md
- 'Stages':
- 'Init Stage': stages/init.md
- 'Pull-Request Voting Stage': stages/prvoting.md
- 'Build Stage': stages/build.md
- 'Additional Unit Test Stage': stages/additionalunittests.md
- 'Integration Stage': stages/integration.md
- 'Acceptance Stage': stages/acceptance.md
- 'Security Stage': stages/security.md
- 'Performance Stage': stages/performance.md
- 'Compliance': stages/compliance.md
- 'Confirm Stage': stages/confirm.md
- 'Promote Stage': stages/promote.md
- 'Release Stage': stages/release.md
- 'SAP Cloud SDK pipeline': pipelines/cloud-sdk/introduction.md
- 'Scenarios':
- 'Build and Deploy Hybrid Applications with Jenkins and SAP Solution Manager': scenarios/changeManagement.md
- 'Build and Deploy SAP UI5 or SAP Fiori Applications on SAP Cloud Platform with Jenkins': scenarios/ui5-sap-cp/Readme.md
- 'Build and Deploy Applications with Jenkins and the SAP Cloud Application Programming Model': scenarios/CAP_Scenario.md
- 'Integrate SAP Cloud Platform Transport Management Into Your CI/CD Pipeline': scenarios/TMS_Extension.md
- Extensibility: extensibility.md
- 'Library steps':
- artifactSetVersion: steps/artifactSetVersion.md
@ -53,28 +76,6 @@ nav:
- uiVeri5ExecuteTests: steps/uiVeri5ExecuteTests.md
- whitesourceExecuteScan: steps/whitesourceExecuteScan.md
- xsDeploy: steps/xsDeploy.md
- 'Pipelines':
- 'General purpose pipeline':
- 'Introduction': stages/introduction.md
- 'Examples': stages/examples.md
- 'Stages':
- 'Init Stage': stages/init.md
- 'Pull-Request Voting Stage': stages/prvoting.md
- 'Build Stage': stages/build.md
- 'Additional Unit Test Stage': stages/additionalunittests.md
- 'Integration Stage': stages/integration.md
- 'Acceptance Stage': stages/acceptance.md
- 'Security Stage': stages/security.md
- 'Performance Stage': stages/performance.md
- 'Compliance': stages/compliance.md
- 'Confirm Stage': stages/confirm.md
- 'Promote Stage': stages/promote.md
- 'Release Stage': stages/release.md
- 'Scenarios':
- 'Build and Deploy Hybrid Applications with Jenkins and SAP Solution Manager': scenarios/changeManagement.md
- 'Build and Deploy SAP UI5 or SAP Fiori Applications on SAP Cloud Platform with Jenkins': scenarios/ui5-sap-cp/Readme.md
- 'Build and Deploy Applications with Jenkins and the SAP Cloud Application Programming Model': scenarios/CAP_Scenario.md
- 'Integrate SAP Cloud Platform Transport Management Into Your CI/CD Pipeline': scenarios/TMS_Extension.md
- Resources:
- 'Required Plugins': jenkins/requiredPlugins.md