Skip to content

Your first Cloud Foundry Application - for Java Developers

In the following section we will give a brief overview of the available MindSphere development environment to help to getting started with developing for the open IoT operating system. This guide describes all steps that are required for deploying, registering and testing your first application with MindAccess DevOps plan and also how to unregister application from Developer Cockpit and delete it from Cloud Foundry .

You can find additional information about Cloud Foundry application on MindSphere in the Cloud Foundry Application Basics.

Getting Started

In order to get started, you first have to prepare your local development environment. This includes the installation and set-up of some software components like Cloud Foundry Command Line Interface (CF CLI) and a source code editor.

Prerequisites

Check the following prerequisites before getting started:

  • User Credentials.
    If you do not already have a MindSphere user account, contact your tenant admin. Tenant admins can read the User Management article to learn more about the user management and provide you the credentials.
  • Cloud Foundry CLI is installed.
    You need the CF CLI to interact with Cloud Foundry, for example for deploying your application. Download Cloud Foundry from https://github.com/cloudfoundry/cli and install CF CLI according to the official instructions. Make sure that you are using the latest version of the CF CLI to prevent compatibility problems.
  • You must have basic Cloud Foundry Knowledge
  • Source code editor is installed.
    You will need a text editor or an IDE to edit your source code. You can use any text editors like Visual Studio Code to create or edit the source code, but you can also use an IDE like IntelliJ IDEA, Eclipse or Spring STS. This tutorial does not contain any IDE specific steps, so you can feel free to choose a source code editor.
  • Compiling source code.
    You will need to compile your source code before pushing it to the CF. Download and install the JDK 1.8. Additionally, you need to install Maven for building the example application.
  • You have at least the Cloud Foundry SpaceDeveloper role to push an application in Cloud Foundry
  • You must have mdsp:core:Developer or mdsp:core:DeveloperAdmin roles

Java Tool Options

If you are working 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

Setting additional proxies may be required in order to in order to reach the Cloud Foundry endpoints from a command line. Please contact your administrator first in case you face any timeouts or connection problems.

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

CMD

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

BASH

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. The following example can be used for your configuration:

Example Configuration for maven

Place the following configuration for maven in 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>PUT-PROXY-IP-HERE</host>
        <port>PUT-PROXY-PORT-HERE</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>PUT-PROXY-IP-HERE</host>
        <port>PUT-PROXY-PORT-HERE</port>
        <nonProxyHosts>local.net|some.host.com</nonProxyHosts>
      </proxy>
  </proxies>
</settings>

Deploy and register sample application on Cloud Foundry

This guide details deploying a sample application on cloud foundry and expose it via the MindSphere Gateway using Developer Cockpit.

These are the following steps:

  1. Deploy a simple "Hello World" application to Cloud Foundry
  2. Configure your application via the Developer Cockpit
  3. Configure application Roles & Scopes
  4. Register your Application

Connecting to Cloud Foundry via CF CLI

Info

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

  1. Optional: Set proxy configuration in CMD or bash.
  2. Login using the cf login -a https://api.cf.eu1.mindsphere.io --sso.
  3. Visit https://login.cf.eu1.mindsphere.io/passcode to get an One Time Code.
  4. Login using the WebKey Link below the Cloud Foundry Login Form. Login with WebKey to Cloud Foundry
  5. Type in your MindSphere Credentials.
  6. Copy the One Time Code and use this code in the CF CLI.
  7. Select your assigned "Cloud Foundry Org".
  8. Select a "Cloud Foundry Space".

There are multiple Spaces in org

"when there are multiple spaces assigned to you, select the specific space you want to work on, eg: Enter number of that space name."

There are no Cloud Foundry Orgs assigned

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

Deploy Application

Before deploying the application you need to download and build it.

  1. Download Hello World application (Java).
  2. Build the application as described in the repository of the example application.
    1
    mvn install 
    
  3. Increase memory and change the host in manifest.yml

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.

Example

  • adjust the manifest.yml

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
4. Push the cloned "Hello World" Application.
1
cf push
5. Go to the cloned Hello-World Application in CLI.
1
cf apps

Routes

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

Create MongoDB Service and bind to created App

You may create an Backing Service and bind it to the previously deployed Java application:

  1. List all possible services.

1
cf marketplace 
2. Create a MongoDB Service: It takes some time until the service is up and running.
1
cf create-service mongodb34 mongodb-xs mongo 
3. Get detailed information about the service: You can access a dashboard that provides backup and restore functionality.
1
cf service mongo 
4. Bind the service instance to your application.

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

1
cf restage hello-spring-cloud  

You will find detailed information about the MongoDB Service here.

View your Application

You need to register your application to access it from your Launchpad. During the registration process, we follow a positive security concept which requires every endpoint of your application to be explicitly registered (which might consist of multiple Cloud Foundry apps).

In the MindSphere context, an application may consist of multiple Cloud Foundry apps with multiple endpoints. To make the distinction easier to follow we are using the term component for Cloud Foundry apps and application (with CF) for the combination of one or more components.

Components

Components define the locations or paths of the microservice(s) implementing the web application or service. The path values need to match at MindSphere Gateway and 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 not visible at MindSphere Gateway. The base path needs to be appended to the component URL.

Configure your application via the Developer Cockpit

This simple example application consists only of a single component with a single endpoint. For real-world application you most likely need to add more components with multiple endpoints. Keep in mind that you need either the mdsp:core:Developer or the mdsp:core:DeveloperAdmin role to access the Developer Cockpit.

  1. Go to your Launchpad and open the Developer Cockpit.
  2. Click on "Create new application". DC Create new application
  3. Type in a application name, e.g. myfirstapp (The name cannot be changed after initial creation)
  4. Type in a version
    • Currently we support a Major.Minor.Patch scheme
    • Versions must start with a major number >= 1
    • The version cannot be changed after saving
  5. Type in a display name that is used for the Launchpad
  6. Upload an icon for your application
  7. Add one component name, e.g. name your Cloud Foundry application hello-spring-cloud

    Component Names

    Please ensure that the names used for the Cloud Foundry applications (e.g. in the manifest.yml) match the names for the components.Otherwise the automatic registration in the production system will fail.

  8. Add at least one endpoint for your component. We just use /** to match all of your application paths

    • You can use arbitrary paths for endpoints
    • The use of /api is not permitted, as this is reserved to call MindSphere APIs from a relative path (e.g. /api/iot/v3/timeseries)
    • You can add wildcards for matching like * (any characters in a path) and ** (any characters and sub paths)
  9. Add 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 exact route (URL) for your deployed application and prefix it with https://. DC Create new application
  10. Click on "Save"

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

Configure Application Roles & Scopes

On the MindSphere platform every application is protected by specific roles and scopes. This serves two purposes:

  1. protects your application from unauthorized access.
  2. It enables you to use MindSphere APIs.

A more detailed introduction about this concept and examples can be found in the section Roles & Scopes. This configuration can be also completed in the Developer Cockpit. During the creation of the application we have automatically created two roles for your application:

  • admin (mdsp:tenantname:appname.admin)
  • user (mdsp:tenantname:appname.user)

Steps

  1. Switch to the Roles & Scopes tab
  2. Select your application from the drop-down
  3. Add one application scope Add application scope
  4. Add one MindSphere API / Core role (Optional) that enables access to the API (in the example below we 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 are not application version specific.

Register your Application

The registration of your application at the MindSphere Gateway enables the route from the MindSphere tenant-specific URL to your internal Cloud Foundry application. A authorized user will also automatically get a oAuth token with all of your configured scopes and MindSphere API roles.

MindSphere follows this scheme for registering applications: <tenantname>-<appname>-<tenantname>.eu1.mindsphere.io In our example the app would be reachable under mymindspheretenant-myfirstapp-mymindspheretenant.eu1.mindsphere.io.

  1. Go to the application details of your app
  2. Click on Register DC Create new application

Application is successfully registered at the MindSphere Gateway.

Assign the application role to yourself

Before you can see the application on the Launchpad you need to assign one of the application roles to your user

  1. Go to your Launchpad and open the User Management.
  2. Select one or more of your application roles and assign them to your user
  3. Open "Roles" and search for the application roles created in the Developer Cockpit.
    Search application Roles
  4. Select each role(ie User and Admin) and click "Edit"
  5. Search for "unassigned Users" and add them to "Assigned Users".
    search user from unassigned
  6. Click on "End editing".
  7. Assign mdsp:mydemo:hellospringcloud.user roles to the user in the same way.

Logout

Currently it is necessary for the user to log out and log in again, after assigning a new role. Logout from MindSphere by clicking Logout on the Launchpad. 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 in the User Management.

Deregister and delete application from Cloud Foundry

The following steps will show how to deregister application from Mindsphere Gateway using Developer Cockpit and delete application from CF via CLI

The guide is split into the following parts:

  1. Unassign the user from application roles
  2. Deregister your application from Developer Cockpit
  3. Delete application from Developer Cockpit
  4. Delete application from Cloud Foundry via CLI

Unassign the user from application roles

Unassigning the application roles to your user will remove the application from your Launchpad.

  1. Go to your Launchpad and open the User Management.
  2. Navigate to application roles and Click Edit.
  3. Drag user from "Assigned Users" to "Unassigned Users" window.
  4. Click on "End editing".
  5. User unassigned from application roles successfully
    unassign user

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

Deregister your application via Developer Cockpit

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

  1. Navigate to Developer Cockpit
  2. Click on your application from application overview
  3. Click on "Deregister" to deregister your application from developer cockpit.
  4. Click on yes to dergister the app from pop up window

Application deregistered successfully.

Delete application from Developer Cockpit

  1. Go to Developer Cockpit and open you application
  2. Click on "Delete"
  3. Click on yes to delete from pop up window

Application deleted from Developer Cockpit, you will not be able to see your application on application overview.

Delete application from Cloud Foundry via CLI

  1. Go to Command Line Terminal
  2. Optional: Set proxy configuration in CMD or bash
  3. Login using the command below

1
cf login -a https://api.cf.eu1.mindsphere.io --sso
4. Visit https://login.cf.eu1.mindsphere.io/passcode to get an One Time Code.
5. Login using the WebKey Link below the Cloud Foundry Login Form.
6. Type in your MindSphere Credentials. 7. Copy the One Time Code and use this code in the CF CLI.
8. Select your assigned Cloud Foundry Org. 9. Select a Cloud Foundry Space.
10. View apps in CLI using command below.

1
cf apps 
11.Delete the app from Cloud Foundry via CLI
1
2
  cf delete hello-spring-cloud
  Really delete the app hello-spring-cloud?> yes 

Application deleted from Cloud Foundry successfully.

Any questions left?

Ask the community


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