Skip to content

Running a Cloud Foundry-Hosted Application - for Java Developers

This guide describes how to deploy, register and test your first application with MindAccess DevOps Plan and how to deregister and delete it again.

For additional information about Cloud Foundry hosted applications on MindSphere, refer to Cloud Foundry Application Basics.

Getting Started

Prerequisites

  • MindSphere User Account
    You need a MindSphere user account. If you don't have one, contact your tenant admin. For instructions, they may refer to Managing User Permissions.
  • Cloud Foundry Command Line Interface (CF CLI)
    You need the CF CLI to interact with Cloud Foundry. Make sure to use the latest version of the CF CLI to prevent compatibility problems. Download it from https://github.com/cloudfoundry/cli and follow the installation instructions.
  • Source code editor or IDE
    You need a source code editor or an IDE to edit the source code of the example application.
  • JDK 1.8 and Maven
    You need JDK 1.8 and Maven for compiling the example application before pushing it to Cloud Foundry.
  • You have at least the Cloud Foundry role SpaceDeveloper to push the application.
  • You have the mdsp:core:Developer or the mdsp:core:DeveloperAdmin role.

Cloud Foundry

New users have to be assigned a role for Cloud Foundry (see Add a new user to Cloud Foundry).

Java Tool Options

If you work behind a company proxy, you have to set the corresponding system properties for gradle, e.g. via environment variable JAVA_TOOL_OPTIONS.

Environment Paths on Windows

Depending on your environment, it may be required to add Maven and the JDK paths to the PATH variable.

Proxy Settings

Setting additional proxies might be required in order to reach the Cloud Foundry endpoints from a command line. Contact your administrator, if you face any timeouts or connectivity problems.

The following two snippets show how to set the proxies for the Cloud Foundry CLI:

1
2
set http_proxy=http://PROXY_IP:PROXY_PORT
set https_proxy=http://PROXY_IP:PROXY_PORT
1
2
export http_proxy=http://PROXY_IP:PROXY_PORT
export https_proxy=http://PROXY_IP:PROXY_PORT

In addition, it might be required to configure the proxies for Maven as well. A working example configuration is given below:

Example Configuration for Maven

Copy the following configuration for Maven into the ~/.m2/settings.xml file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
<settings>
  <proxies>
      <proxy>
        <id>http_proxy</id>
        <active>true</active>
        <protocol>http</protocol>
        <username>proxyuser</username>
        <password>proxypass</password>
        <host>{yourProxyIP}</host>
        <port>{yourProxyPort}</port>
        <nonProxyHosts>local.net|some.host.com</nonProxyHosts>
      </proxy>
      <proxy>
        <id>https_proxy</id>
        <active>true</active>
        <protocol>https</protocol>
        <username>proxyuser</username>
        <password>proxypass</password>
        <host>{yourProxyIP}</host>
        <port>{yourProxyPort}</port>
        <nonProxyHosts>local.net|some.host.com</nonProxyHosts>
      </proxy>
  </proxies>
</settings>

Deploy and Register an Application

This section shows how to deploy a sample application on Cloud Foundry and expose it at the MindSphere Gateway using the Developer Cockpit.

Prepare the Application

  1. Download Hello World application (Java).
  2. Build the application as described in the repository using:

    1
    mvn install
    
  3. Increase the memory and change the host in manifest.yml as shown below - replace appName by an arbitrary name for the application and tenantName by the name of your tenant:

    1
    2
    3
    4
    5
    6
    7
    applications:
    - name: ui
      instances: 1
      routes:
      - route: {appName}-{tenantName}.apps.eu1.mindsphere.io
      path: target/hello-spring-cloud-0.0.1.BUILD-SNAPSHOT.jar
      memory: 1GB
    

Routes

In order to create a route, always append your tenant name to the app name when you specify the Cloud Foundry host.

Deploy the Application to Cloud Foundry via CF CLI

  1. Configure the proxy settings, if necessary.
  2. Log in using cf login -a https://api.cf.eu1.mindsphere.io --sso.
  3. Visit https://login.cf.eu1.mindsphere.io/passcode to get a One Time Code.
    • Log in using the WebKey Link below the Cloud Foundry Login Form. Login with WebKey to Cloud Foundry
  4. Copy the One Time Code and use it in the CF CLI.
  5. Select your Cloud Foundry Org.

    No Cloud Foundry Orgs assigned

    If you do not see any Cloud Foundry Orgs, you need to be added to your Org. Refer to the How Tos for Cloud Foundry.

  6. Select the Cloud Foundry Space you want to work on.

  7. Push the application to your Cloud Foundry Space using:

    1
    cf push
    
  8. Get a list of the applications available in your Cloud Foundry Space using:

    1
    cf apps
    

Application Routes

The routes shown after the deployment are not exposed in the internet. You need to register your application in the Developer Cockpit before it is reachable via the Internet.

Outbound IP Addresses

MindSphere applications running on Cloud Foundry access the internet via a NAT gateway. If these applications need to access your enterprise network, your inbound firewall must allow the NAT gateway's IP addresses:

1
2
3
35.156.223.10
18.194.162.141
18.194.195.179

Bind a Backing Service to the Application (Optional)

This step shows how to create a MongoDB Service and bind it to the previously deployed application. For a list of all available Backing Services, use the following command:

1
cf marketplace
  1. Create a MongoDB Service. Note that it takes some time until the service is up and running.

    1
    cf create-service mongodb34 mongodb-xs mongo
    
  2. For detailed information about the service instance, i.e., a dashboard that provides backup and restore functionality, use the following command:

    1
    cf service mongo
    
  3. Bind the service instance to your application.

    1
    cf bind-service hello-spring-cloud mongo
    
  4. Restage your application in order to activate the service binding in your application.

    1
    cf restage hello-spring-cloud
    

Configure the Application via the Developer Cockpit

Components

An application on MindSphere may consist of multiple Cloud Foundry apps with multiple endpoints. For clear distinction, Cloud Foundry apps are referred to as component.

The example application consists of one component with a single endpoint. Real-world applications usually consist of more components with multiple endpoints.

  1. Open the Developer Cockpit from the Launchpad and select the "Dashboard" tab.
  2. Click on "Create new application".
  3. Enter an application name, e.g. myfirstapp. (The name cannot be changed after initial creation!)
  4. Enter a version number.
    • MindSphere supports a Major.Minor.Patch scheme.
    • Versions must start with a major number >= 1.
    • The version cannot be changed after saving.
  5. Enter a display name to be displayed in the Launchpad.
  6. Upload an icon for your application.
  7. Add a component name, e.g. hello-spring-cloud.

    Component Names

    The component names must match the names defined for the Cloud Foundry applications in the manifest.yml. Otherwise, the automatic registration in the production system will fail.

  8. Add at least one endpoint for your component. Use /** to match all of your application paths as shown below.

    • You can use arbitrary paths for endpoints.
    • The use of /api is not permitted, as this is reserved for calling MindSphere APIs from a relative path (e.g. /api/iot/v3/timeseries).
    • You can use wildcard characters. * matches any character in a path and ** any characters and sub paths. DC Create new application

    Component Paths

    The path values defined at MindSphere Gateway must match with the corresponding component. See MindSphere Gateway for a complete list of possible mappings of gateway to component paths. A component can have a base path, which is not visible at MindSphere Gateway. The component URL needs to be appended by the base path.

  9. Enter the internal Cloud Foundry URL of your application, e.g. https://hello-spring-cloud-myMindsphereTenant.apps.eu1.mindsphere.io.

    • Use cf app APPNAME to get the URL for your deployed application and prefix it with https://.
  10. Click on "Save".

You are redirected to the application details. Your application is in the IN-Development state and is ready for registration.

Configure the Application Roles & Scopes

Every application in MindSphere is protected from unauthorized access by specific roles and scopes. MindSphere automatically creates two default roles for new applications:

  • admin (mdsp:{tenantName}:{appName}.admin)
  • user (mdsp:{tenantName}:{appName}.user)

The roles and scopes are configured using the Developer Cockpit. You can also assign Core roles, which grant access to MindSphere APIs:

  1. Switch to the "Roles & Scopes" tab.
  2. Select the application from the drop-down.
  3. Create an application scope and select which roles it is assigned to. Add application scope
  4. Add a Core role, that enables access to the respective API (optional). The image below shows how to get reading access to the Time Series APIs. DC Create new application
  5. Saving is not required, unless you change one of the associations to the application specific roles afterwards.

Roles & Scopes for Applications

The roles and scopes configuration for applications is not specific for an application version.

Register the Application

An application must be registered at the MindSphere Gateway to access it from the Launchpad. This enables the route from the tenant-specific MindSphere URL to your internal Cloud Foundry application. The registration process follows a positive security concept, which requires every endpoint of the application to be explicitly registered.

  1. Open the application details.
  2. Click on "Register".

MindSphere registers applications using the following scheme: {tenantName}-{appName}-{tenantName}.eu1.mindsphere.io In this example, the application would be reachable under myMindsphereTenant-myfirstapp-myMindsphereTenant.eu1.mindsphere.io.

Assign the Application Roles

Before you can see the application on the Launchpad, you need to assign one of the application roles to your user. An authorized user automatically gets an OAuth token with all configured scopes and MindSphere API roles.

  1. Start the Settings from the Launchpad and open the Roles tab. Search application Roles
  2. Select one or more of the application roles and assign them to your user.
  3. Click on "End editing".
  4. Log out of from MindSphere and log in again.

Logout

It is necessary for the user to log out and log in again, after assigning a new role. In rare cases it might take a couple of minutes until the role assignment has been propagated through the system.

You should be able to see your application on the Launchpad. If you do not see the application, verify that you have assigned yourself the application specific role.

Deregister and Delete an Application from Cloud Foundry

This section shows how to deregister an application from the MindSphere Gateway using the Developer Cockpit and how to delete the application from Cloud Foundry via CF CLI.

Unassign the Application Roles

Unassigning the application roles from your user removes the application from your Launchpad.

  1. Start the Settings from the Launchpad and open the Roles tab.
  2. Drag your user from "Assigned Users" to "Unassigned Users".
  3. Click on "End editing".

You should not be able to see your application on the Launchpad anymore.

Deregister the Application

The deregistration of the application at the MindSphere Gateway disables the route from the tenant-specific MindSphere URL to your internal Cloud Foundry application.

  1. Navigate to Developer Cockpit.
  2. Select the application.
  3. Click on "Deregister" and confirm.

Delete the Application via the Developer Cockpit

  1. Select the application in the Developer Cockpit.
  2. Click on "Delete" and confirm.

Delete the Application from Cloud Foundry via CF CLI

  1. Configure the proxy settings, if necessary.
  2. Log in via the CF CLI using cf login -a https://api.cf.eu1.mindsphere.io --sso.
  3. Visit https://login.cf.eu1.mindsphere.io/passcode to get a One Time Code.
  4. Copy the One Time Code and use it in the CF CLI.
  5. Select your assigned Cloud Foundry Org.
  6. Select the respective Cloud Foundry Space.
  7. Get a list of all available apps using cf apps.
  8. Delete the app from Cloud Foundry via cf delete hello-spring-cloud and confirm.

Any questions left?

Ask the community


Except where otherwise noted, content on this site is licensed under the MindSphere Development License Agreement.