Skip to content

README.md

Latest commit

 

History

History
265 lines (223 loc) · 10.9 KB

README.md

File metadata and controls

265 lines (223 loc) · 10.9 KB

Changelog Github repo

@sap-ux/deploy-tooling

@sap-ux/deploy-tooling exposes the capabilities of custom tasks to deploy and undeploy SAP Fiori projects against ABAP servers.

Pre-requisites

  • SAP component SAP_UI 7.53 or higher is installed in your SAP system
  • Service needs to be enabled and accessible from your development environment, how to check this
  • For operations on a SAPUI5 ABAP repository, you need the S_DEVELOP authorization, how to check this

CLI

The module also exposes two commands deploy and undeploy.

Install

`npm install @sap-ux/deploy-tooling --save-dev`
# or
yarn add @sap-ux/deploy-tooling --dev

Verify local installation

npx deploy -h
# or
./node_modules/.bin/deploy -h

Usage

deploy [options]
# or
undeploy [options]

By default, YAML configuration is read from ui5-deploy.yaml, found in the root of your project when the deploy | undeploy commands are executed.

To change the default configuration location, run;

Deploy

deploy -c myproject/my-deploy-config.yaml
# or
deploy --config myproject/my-deploy-config.yaml

Undeploy

undeploy -c myproject/my-undeploy-config.yaml
# or
undeploy --config myproject/my-undeploy-config.yaml

Minimal Configuration

This is the minimal custom task configuration for deployment using package $TMP, without the change being recorded in a transport request.

Note: The package name $TMP must be uppercase. If a lowercase variant, for example, $tmp is detected in the configuration, it is automatically normalized to $TMP and a warning is logged because lowercase values can cause deployment failures.

- name: abap-deploy-task
  configuration:
    app:
      name: Z_TEST
      package: $TMP
    target:
      url: https://target.example
    exclude:
      - /test/

Credentials

You can provide credentials for the ABAP system using environment variables. The credentials are required for authentication against the ABAP system. Plain text credentials are not supported, use environment variables instead.

- name: abap-deploy-task
  configuration:
    credentials:
      username: env:XYZ_USER
      password: env:XYZ_PASSWORD
    app:
      name: Z_TEST
      package: $TMP
    target:
      url: https://target.example
    exclude:
      - /test/

Create an .env file in the root of your project with the following content:

XYZ_USER=your-username
XYZ_PASSWORD=your-password

Configuration with logging enabled

Set the level of detail for log messages, default is Info;

Error = 0,
Warn = 1,
Info = 2,
Verbose = 3,
Debug = 4,
Silly = 5

Custom task YAML Configuration example:

- name: abap-deploy-task
  configuration:
    log: 5
    app:
      name: Z_TEST
      package: $TMP
    target:
      url: https://target.example
    exclude:
      - /test/

Or setting verbose: true will set the log level to Silly:

- name: abap-deploy-task
  configuration:
    verbose: true
    app:
      name: Z_TEST
      package: $TMP
    target:
      url: https://target.example
    exclude:
      - /test/

Deploy

The deploy command executes the same functionality as the abap-deploy UI5 task independent of the ui5 build execution. This allows to separate the build and the deployment process e.g. for CI/CD or to provide configurations as CLI args instead of having them defined in the ui5.yaml - nevertheless, the ui5.yaml is always required as a basis for the configuration.

Usage: deploy [options]

Options:
  -c, --config <path-to-yaml>          Path to config yaml file
  -y, --yes                            yes to all questions (default: false)
  -n, --no-retry                       do not retry if deploy fails for any reason, for CI/CD pipeline flows this option needs to be included (default: false)
  --verbose                            verbose log output (default: false)
  --destination  <destination>         Destination in SAP BTP pointing to an ABAP system
  --url <target-url>                   URL of target ABAP system
  --connect-path <path>                (Optional) Service URL path used to retrieve credentials from secure storage
  --service                            (Optional) Alias for the target SAPUI5 Respository OData Service
  --client <sap-client>                Client number of target ABAP system
  --cloud                              target is an ABAP Cloud system
  --cloud-service-key <file-location>  JSON file location with the ABAP cloud service key.
  --cloud-service-env                  Load ABAP cloud service properties from either a .env file or your environment variables. Secrets in your .env should not be committed to source control.
  --username                           ABAP Service username, plain text credentials are not supported, use environment variables
  --password                           ABAP Service password, plain text credentials are not supported, use environment variables
  --authentication-type                Authentication type for the app (e.g. 'basic', 'reentranceTicket'). Required for 'reentranceTicket'.
  --create-transport                   Create a transport request during deployment/undeployment
  --transport <transport-request>      Transport number to record the change in the ABAP system
  --name <bsp-name>                    Project name of the app
  --no-strict-ssl                      Deactivate SSL certificate validation, enabled by default
  --test                               Run in test mode. ABAP backend reports deployment errors without actually deploying. (use --no-test to deactivate it)
  --package <abap-package>             Package name for deploy target ABAP system
  --description <description>          Project description of the app
  --safe                               Prevents accidentally breaking deployments.
  --keep                               Keep a copy of the deployed archive in the project folder.
  --archive-url <url>                  Download app bundle from this url and upload this bundle for deployment
  --archive-path <path>                Provide path of the app bundle for deployment
  --archive-folder <path>              Provide path to a folder for deployment
  -v, --version                        version of the deploy tooling
  -h, --help                           display help for command

Deploy Examples

Example 1 - Deploy to an ABAP Cloud system with strict SSL disabled

deploy --url <target-abap-system> --cloud true --name <app-name> --description '<app-description>' --package <package-name> --transport <transport-request> --no-strict-ssl

Using YAML configuration;

# yaml-language-server: $schema=https://sap.github.io/ui5-tooling/schema/ui5.yaml.json

specVersion: "4.0"
metadata:
  name: my.namespace.myappname
type: application
builder:
  resources:
    excludes:
      - /test/**
      - /localService/**
  customTasks:
    - name: abap-deploy-task
      afterTask: generateCachebusterInfo
      configuration:        
        target:
          url: <target-abap-system>
          cloud: true
        app:
          name: <app-name>
          description: <app-description>
          package: <package-name>
          transport: <transport-request>
        exclude:
          - /test/

Deploy CLI command;

deploy -c ui5-deploy.yaml --no-strict-ssl

Undeploy

The undeploy command allows undeploying a previously deployed application. This functionality is only available as CLI command and not as ui5 task.

Usage: undeploy [options]

Options:
  -c, --config <path-to-yaml>          Path to config yaml file
  -y, --yes                            yes to all questions (default: false)
  -n, --no-retry                       do not retry if undeploy fails for any reason, for CI/CD pipeline flows this option needs to be included (default: false)
  --verbose                            verbose log output (default: false)
  --destination  <destination>         Destination in SAP BTP pointing to an ABAP system
  --url <target-url>                   URL of target ABAP system
  --service                            (Optional) Alias for the target SAPUI5 Respository OData Service
  --client <sap-client>                Client number of target ABAP system
  --cloud                              target is an ABAP Cloud system
  --cloud-service-key <file-location>  JSON file location with the ABAP cloud service key.
  --cloud-service-env                  Load ABAP cloud service properties from either a .env file or your environment variables
  --username                           ABAP Service username, plain text credentials are not supported, use environment variables
  --password                           ABAP Service password, plain text credentials are not supported, use environment variables
  --authentication-type                Authentication type for the app (e.g. 'basic', 'reentranceTicket'). Required for 'reentranceTicket'.
  --transport <transport-request>      Transport number to record the change in the ABAP system
  --create-transport                   Create a transport request during deployment
  --package <abap-package>             Package name for deploy target ABAP system (only required when --create-transport is used)
  --name <bsp-name>                    Project name of the app
  --no-strict-ssl                      Deactivate SSL certificate validation, enabled by default
  --test                               Run in test mode. ABAP backend reports undeployment errors without actually undeploying (use --no-test to deactivate it).
  -v, --version                        version of the deploy tooling
  -h, --help                           display help for command

Proxy Support

To enable support for TLS (Transport Layer Security) connections when using HTTPS_PROXY, update your environment by setting the HTTPS_PROXY environment variable, as shown;

export HTTPS_PROXY=<YOUR-PROXY:PORT>

In order to support credentials in the proxy URL, you can set the HTTPS_PROXY environment variable to include the username and password in the URL. For example:

export HTTPS_PROXY=http://user:[email protected]:3128

Ensure you restart any running processes to apply the changes.

Example Scenario

If you're using a proxy server to route your HTTPS traffic, the proxy server will need to create a secure, TLS-encrypted connection to the target server on your behalf. tls.connect() will be used to establish that encrypted tunnel between your client, the proxy, and the server.