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.
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.
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
SpaceDeveloperrole to push an application in Cloud Foundry
- You must have
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
Environment Paths on Windows
Depending on your environment it may be required to add Maven and the JDK paths to the
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:
set http_proxy=http://PROXY_IP:PROXY_PORT set https_proxy=http://PROXY_IP:PROXY_PORT
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
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:
- Deploy a simple "Hello World" application to Cloud Foundry
- Configure your application via the Developer Cockpit
- Configure application Roles & Scopes
- Register your Application
Connecting to Cloud Foundry via CF CLI¶
New users have to be assigned a role for Cloud Foundry (see Add a new user to Cloud Foundry).
- Optional: Set proxy configuration in CMD or bash.
- Login using the
cf login -a https://api.cf.eu1.mindsphere.io --sso.
- Visit https://login.cf.eu1.mindsphere.io/passcode to get an One Time Code.
- Login using the WebKey Link below the Cloud Foundry Login Form.
- Type in your MindSphere Credentials.
- Copy the One Time Code and use this code in the CF CLI.
- Select your assigned "Cloud Foundry Org".
- 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
Before deploying the application you need to download and build it.
- Download Hello World application (Java).
- Build the application as described in the repository of the example application.
- Increase memory and change the host in
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.
- adjust the
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
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:
- List all possible services.
cf create-service mongodb34 mongodb-xs mongo
cf service mongo
cf bind-service hello-spring-cloud mongo
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 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.
- Go to your Launchpad and open the Developer Cockpit.
- Click on "Create new application".
- Type in a application name, e.g.
myfirstapp(The name cannot be changed after initial creation)
- Type in a version
- Currently we support a
- Versions must start with a major number >= 1
- The version cannot be changed after saving
- Currently we support a
- Type in a display name that is used for the Launchpad
- Upload an icon for your application
Add one component name, e.g. name your Cloud Foundry application
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.
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
/apiis not permitted, as this is reserved to call MindSphere APIs from a relative path (e.g.
- You can add wildcards for matching like
*(any characters in a path) and
**(any characters and sub paths)
- Add the internal Cloud Foundry URL of your application, e.g.
cf app APPNAMEto get the exact route (URL) for your deployed application and prefix it with
- 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:
- protects your application from unauthorized access.
- 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 (
- user (
- Switch to the Roles & Scopes tab
- Select your application from the drop-down
- Add one application scope
- 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)
- 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:
In our example the app would be reachable under
- Go to the application details of your app
- Click on Register
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
- Go to your Launchpad and open the User Management.
- Select one or more of your application roles and assign them to your user
- Open "Roles" and search for the application roles created in the Developer Cockpit.
- Select each role(ie User and Admin) and click "Edit"
- Search for "unassigned Users" and add them to "Assigned Users".
- Click on "End editing".
mdsp:mydemo:hellospringcloud.userroles to the user in the same way.
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:
- Unassign the user from application roles
- Deregister your application from Developer Cockpit
- Delete application from Developer Cockpit
- 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.
- Go to your Launchpad and open the User Management.
- Navigate to application roles and Click Edit.
- Drag user from "Assigned Users" to "Unassigned Users" window.
- Click on "End editing".
- User unassigned from application roles successfully
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.
- Navigate to Developer Cockpit
- Click on your application from application overview
- Click on "Deregister" to deregister your application from developer cockpit.
- Click on yes to dergister the app from pop up window
Application deregistered successfully.
Delete application from Developer Cockpit¶
- Go to Developer Cockpit and open you application
- Click on "Delete"
- 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¶
- Go to Command Line Terminal
- Optional: Set proxy configuration in CMD or bash
- Login using the command below
cf login -a https://api.cf.eu1.mindsphere.io --sso
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.
cf delete hello-spring-cloud Really delete the app hello-spring-cloud?> yes
Application deleted from Cloud Foundry successfully.
Any questions left?
Except where otherwise noted, content on this site is licensed under the MindSphere Development License Agreement.