Skip to content

Deploying Mendix Apps to MindSphere

This documentation is meant for developers who want to deploy a Mendix app to the MindSphere platform.

Code Blocks

Code blocks with line numbers provide an easy copy functionality. Use it by hovering the cursor over the code block and clicking on the copy icon at its top right.

Prerequisites

Preparing the Mendix App for MindSphere

Option A: Using the MindSphere Starter App

Existing Apps

If you want to deploy an already existing app to MindSphere, skip this step and jump to Integrating the MindSphere Theme Pack and Modules.

Use the MindSphere Starter App when developing a new Mendix app for MindSphere. This contains all building blocks required for deploying apps to MindSphere.

  1. Open the Mendix Studio Pro.
  2. Click on the icon at the top-right of the menu bar to open the Mendix App Store.

    starting point

  3. Enter "MindSphere Starter Application" and press enter.

  4. Select the MindSphere Starter Application from the search results.

    starting point

  5. Click Download to create a new app project using this app.

    starting point

  6. Select where to store the app and enter an app name and the project directory. Then click OK.

    starting point

    App name

    If you want to keep your app name on Mendix and on MindSphere consistent, use an app name that will be accepted by the Developer Cockpit.

Option B: Integrating the MindSphere Theme Pack and Modules

MindSphere Starter App

If you are using the MindSphere Starter App, skip this step and jump to Configuring the Modules.

Mendix apps have to integrate the MindSphere Theme Pack, the MindSphere Single Sign-On module and the MindSphere OS Bar Connector. Download these mandatory elements using following links to integrate them a posteriori into existing Mendix apps.

  • MindSphere Theme Pack in the Mendix App Store
    This theme pack adjusts the styling of Mendix apps and includes a general patch to run Mendix applications on MindSphere as well as changes to the index.html required for the MindSphere modules. For detailed information about the theme pack, refer to the Mendix documentation.
  • MindSphere Single Sign-On module in the Mendix App Store
    This module enables Mendix apps to use MindSphere Single Sign-On which allows logged in MindSphere users to access the app without another login. In addition, it enables developers to test their app locally. For detailed information about the module, refer to the Mendix documentation.
  • MindSphere OS Bar module in the Mendix App Store
    This module integrates the MindSphere OS Bar, which is mandatory for every MindSphere app. It connects all MindSphere apps on a UI level, displays app information as shown below, routes back to the Launchpad, and logs the user out of MindSphere. For detailed information about the module, refer to the Mendix documentation.

    OS Bar

    MindSphere OS Bar download location

    The MindSphere OS Bar will always be downloaded from a EU1 location, even when you working against EU2 or any other platform. This is intended behaviour. The OS Bar provided is compatible to all other target platforms as well.

Configuring the Modules

Configuring the MindSphere Single Sign-On

  1. Double click on the CockpitApplicationName constant.

    SSO

  2. Replace the Default value Change me in the Value section by the name you will use for configuring your app in MindSphere using the Developer Cockpit.

    Configure App Name

    Info

    Do not change the Name field at the top of this dialogue.

    The following constraints apply for app names when registering apps in MindSphere:

    • Contains only lowercase alphanumeric characters and special characters -, _ and . are not allowed
    • Starts with a letter
    • Length does not exceed 20 characters
    • Is unique within your tenant
  3. If your tenant is not in region Europe 1 e.g. MindSphere on Azure, also adjust the MindSphereGatewayURL and the PublicKeyURL constants.

    • The MindSphereGatewayURL specifies the base URL for all requests to MindSphere APIs.
    • The PublicKeyURL defines the location of the public key, which is used for token validation during the login process.
Click here if you don't use the MindSphere starter or example app!

The RegisterSingleSignOn must be configured as After startup microflow if you don't use the MindSphere starter or example app:

  1. Open the project settings by double-clicking on the Project > Settings of the Project Explorer.
  2. Switch to the Runtime tab.
  3. Select the RegisterSingleSignOn as the After startup microflow. Alternatively, add it to your existing After startup microflow.

Configuring the App Information (optional)

The app information is displayed if the user clicks on the app name in the MindSphere OS Bar. Configure the app information by following the instructions below. OS Bar App Information

  1. Double-click the string constant Config of the MindSphereOSBarConfig module.
  2. Enter the app information as a JSON object into the Default value field: OSBarConfig

    For a description of the available configuration parameters and a sample JSON object, refer to the MindSphere OS Bar documentation.

Deploying the Mendix App to Cloud Foundry

Info

Mendix applications can be hosted outside MindSphere. In that case they must provide a mechanism which handles user credentials for accessing MindSphere APIs. This is not recommended and not covered by this documentation.

Creating a Mendix Deployment Package

Commit Changes

If you are working on a Project hosted on the Mendix TeamServer, you will need to commit your changes first before creating the deployment package. For more information refer Developing Mendix Apps for MindSphere.

  1. Open the app in the Mendix Studio Pro.
  2. Select Project > Create Deployment Package....

    Create Deployment Package

  3. Select the desired Development line and Revision and set the version number.

  4. (Optional) Add a description and adjust the path for the deployment package if desired. By default, the deployment package is created in the releases folder of your project.
  5. Click OK.

The location of the new deployment package will be displayed in an information window.

Deploying the App to Cloud Foundry via CF CLI

  1. Open a command line interface (CLI) inside the folder with the deployment package.
  2. Configure the proxy settings, if necessary.

    Click here for detailed information on proxy settings

    If you are in a company network behind a proxy, you may have to set the proxies to reach the Cloud Foundry endpoints. Contact your administrator, if you face any timeouts or connectivity problems.

    Set the proxies for the Cloud Foundry CLI as shown below:

    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
    
  3. Enter cf login -a https://api.cf.{region}.{mindsphere-domain} --sso.

  4. Open the URL printed by the CLI and log in using your WebKey credentials to get a One Time Code.
  5. Enter the One Time Code in the CLI.
  6. Select your Cloud Foundry org and space using the following command:

    1
    cf target -o {org_name} -s {space_name}
    

    No Cloud Foundry Orgs displayed

    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.

  7. Create a PostgreSQL Service instance. Note that it takes some time until the instance is up and running.

    1
    cf create-service {service_plan} {instance_name}
    
    1
    cf create-service postgresql10 postgresql-xs my-postgreSQL
    

    Service plans

    With the command cf marketplace you can checkout which version of the postgres service is available e.g. postgresql94 or postgresql10

  8. Check if your service instance is running using the following command:

    1
    cf services
    
  9. Create a manifest.yml file inside the folder with the deployment package with at least the following content:

    1
    2
    3
    4
    5
    6
    applications:
    - name: {app_name}
      disk_quota: {required_quota}
      memory: {required_memory}
      services:
      - {instance_name}
    
    1
    2
    3
    4
    5
    6
    applications:
    - name: my-app
      disk_quota: 512M
      memory: 512M
      services:
      - my-postgreSQL
    

    Info

    Mendix apps require at least 512M of memory and disk quota.
    For more information on the configuration of manifest files, refer to the documentation on Manifest Files.

  10. Push the application to your Cloud Foundry space using:

    1
    cf push -p "{deployment_package_name}"
    

Configuring the Mendix App in MindSphere

Configuring the Mendix App in 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.

  1. Open the Developer Cockpit from the Launchpad and select the Dashboard tab.
  2. Click on Create new application.
  3. Select Type Standard and Infrastructure MindSphere Cloud Foundry.
  4. Enter an arbitrary Display Name and an Internal Name which will be part of the application URL. The Internal Name cannot be changed after initial creation!

    Internal Name

    The Internal Name must be equal to the CockpitApplicationName configured in the MindSphere Single Sign-On module. Internal Name Developer Cockpit

  5. 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.
  6. Upload an icon for your application.
  7. Enter the component name.

    Component Names

    Component names must match the names of the Cloud Foundry applications in the manifest.yml. Otherwise, the automatic registration in the production system will fail.

  8. Add an endpoint for your component and use /** to match all of your application paths as shown below. DC Create new application

    Info

    For more details refer to Running a Cloud Foundry Application.

  9. Enter the Cloud Foundry URL of your application.

    • Use cf app {app_name} to get the URL for your deployed application and prefix it with https://.
  10. Set the following content security policy to ensure that the MindSphere OS Bar and the Mendix Feedback widget are loaded correctly:

    • for Region Europe 1 (AWS) use:
      1
      default-src 'self' 'unsafe-inline' 'unsafe-eval' static.eu1.mindsphere.io sprintr.home.mendix.com; font-src 'self' static.eu1.mindsphere.io fonts.gstatic.com; style-src * 'unsafe-inline'; script-src 'self' 'unsafe-inline' 'unsafe-eval' static.eu1.mindsphere.io sprintr.home.mendix.com; img-src * data:;
      
    • for Region Europe 2 (Azure) use:
      1
      default-src 'self' 'unsafe-inline' 'unsafe-eval' static.eu1.mindsphere.io sprintr.home.mendix.com; img-src 'self' static.eu1.mindsphere.io sprintr.home.mendix.com data: uistorageaccountprod.blob.core.windows.net; font-src 'self' data: *.eu2.mindsphere.io uistorageaccountprod.blob.core.windows.net static.eu1.mindsphere.io; style-src 'self' 'unsafe-inline' *.eu2.mindsphere.io uistorageaccountprod.blob.core.windows.net static.eu1.mindsphere.io sprintr.home.mendix.com home.mendix.com; script-src 'self' 'unsafe-inline' 'unsafe-eval' *.eu2.mindsphere.io uistorageaccountprod.blob.core.windows.net static.eu1.mindsphere.io sprintr.home.mendix.com home.mendix.com; connect-src 'self' 'unsafe-inline' *;
      

    Info

    These content security policy settings are needed to ensure that the MindSphere OS Bar and the Mendix Feedback Widget are loaded correctly. You may need to set additional CSP settings if you make additional calls to other domains (for example, if you use Google maps from maps.googleapi.com).

  11. Click on Save.

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

Configuring the Mendix App 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:{tenant_name}:{app_name}.admin)
  • user (mdsp:{tenant_name}:{app_name}.user)

For creating custom application roles, refer to Securing your own Application. The permissions for these roles are configured using the Developer Cockpit. You can assign Core roles, which grant access to MindSphere APIs, and define application scopes:

  1. Switch to the Authorization Management tab.
  2. Select the application.
  3. Create an application scope and select which MindSphere roles it is assigned to.

    Info

    The application scope must be named so that it can be mapped to a Mendix user role via case-insensitive comparison of the names. For detailed information refer to the roles and scopes information for developing Mendix apps.

    Add application scope If you are using the starter app, create a user scope and an admin scope as shown below: Scopes Starter App

Registering the Mendix App

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. Switch to the Dashboard tab.
  2. Open the application details.
  3. Click on Register.

MindSphere registers applications using the following scheme: {tenant_name}-{app_name}-{tenant_name}.{region}.mindsphere.io

For more information regarding the registration scheme, refer Gateway-URL-schemas

Assigning the Mendix App Roles

Applications only appear on the Launchpad, if one of the application scopes is present in the user's OAuth token. This is the case, if the user is assigned one of the application roles:

  1. Open the Settings app from the Launchpad and switch to the Roles tab. Search application Roles
  2. Select an application role and click on Edit assignments.
  3. Assign one or more users to the application role.
  4. Click on End editing.
  5. Log out of from MindSphere and log in again.

Logout

The user token is only updated with the new scopes after logging out and logging in again. In rare cases it might take a couple of minutes until the role assignment has been propagated through the system.

Your application is now available in your Launchpad. Your OAuth token contains all scopes and Core Roles defined in the application role. If you do not see the application, verify that you have assigned yourself the application specific role.

Any questions left?

Ask the community


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