Run Mendix in Cloud Foundry

There are specific guides for deploying Mendix apps to the Pivotal Web Services and HP Helion Development Platform flavors of Cloud Foundry on our documentation page. This page will document the more low-level details and CLI instructions.

Deploying using the CLI

Install cloud foundry command line

Install the Cloud Foundry command line executable. You can find this on the releases page. Set up the connection to your preferred Cloud Foundry environment with cf login and cf target.

Push your app

We push an mda (Mendix Deployment Archive) that was built by the Mendix Business Modeler to Cloud Foundry.

cf push <YOUR_APP> -b https://github.com/mendix/cf-mendix-buildpack -p <YOUR_MDA>.mda

We can also push a project directory. This will move the build process (using mxbuild) to Cloud Foundry:

cd <PROJECT DIR>; cf push -b https://github.com/mendix/cf-mendix-buildpack

Note that building the project in Cloud Foundry takes more time and requires enough memory in the compile step.

Configuring admin password

The first push generates a new app, but deployment will fail because the buildpack requires an ADMIN_PASSWORD variable and a connected PostgreSQL or MySQL service. So go ahead and set this up after the first failed push.

Keep in mind that the admin password should comply with the policy you have set in the Modeler.

cf set-env <YOUR_APP> ADMIN_PASSWORD "<YOURSECRETPASSWORD>"

Connecting a Database

You also need to connect a PostgreSQL or MySQL instance which allows at least 5 connections to the database. Find out which services are available in your Cloud Foundry instance like this.

cf marketplace

In our trial we found the service elephantsql which offered the free turtle plan. All you need to do is give it a name and bind it to your application.

cf create-service elephantsql turtle <SERVICE_NAME>

cf bind-service <YOUR_APP> <SERVICE_NAME>

Note that not all database service set a DATABASE_URL value. If this is not done automatically you need to set this variable manually using the details included in the service, as the buildpack will look for this variable for the database connection string.

Now we need to push the application once more.

cf push <YOUR_APP> -b https://github.com/mendix/cf-mendix-buildpack -p <YOUR_MDA>.mda

You can now log in to your application with the specified password.

Configuring Constants

The default values for constants will be used as defined in your project. However, you can override them with environment variables. You need to replace the dot with an underscore and prefix it with MX_. So a constant like Module.Constant with value ABC123 could be set like this:

cf set-env <YOUR_APP> MX_Module_Constant "ABC123"

After changing environment variables you need to restart your app. A full push is not necessary.

cf restart <YOUR_APP>

Configuring Scheduled Events

The scheduled events can be configured using environment variable SCHEDULED_EVENTS.

Possible values are ALL, NONE or a comma separated list of the scheduled events that you would like to enable. For example: ModuleA.ScheduledEvent,ModuleB.OtherScheduledEvent

When scaling to multiple instances, the scheduled events that are enabled via the settings above will only be executed on instance 0. The other instances will not execute scheduled events at all.

Configuring External Filestore

Mendix 5.15 and up can use external file stores with an S3 api. Use the following environment variables to enable this.

S3_ACCESS_KEY_ID: credentials access key
S3_SECRET_ACCESS_KEY: credentials secret
S3_BUCKET_NAME: bucket name

The following environment variables are optional:

S3_PERFORM_DELETES: set to false to never delete items from the filestore. This is useful when you use the filestore without a backup mechanism.
S3_KEY_SUFFIX: if your bucket is multi-tenant you can append a string after each object name, you can restrict IAM users to objects with this suffix.
S3_ENDPOINT: for S3 itself this is not needed, for S3 compatible object stores set the domain on which the object store is available.
S3_USE_V2_AUTH: use Signature Version 2 Signing Process, this is useful for connecting to S3 compatible object stores like Riak-CS, or Ceph.
S3_ENCRYPTION_KEYS: a JSON string containing a list of keys which can be used to encrypt and decrypt data at rest in S3.
S3_USE_SSE: if set to true this will enable Server Side Encryption in S3, available from Mendix 6.0

Configuring the Java heap size

The default java heap size is set to the total available memory divided by two. If your application's memory limit is 1024M, the heap size is set to 512M. You might want to tweak this to your needs by using another environment variable in which case it is used directly.

cf set-env <YOUR_APP> HEAP_SIZE 512M

Configuring the Java version

The default Java version is 8 for Mendix 5.18 and higher. If you want to force Java 7 or 8, you can set the environment variable JAVA_VERSION to 7 or 8.

cf set-env <YOUR_APP> JAVA_VERSION 8

Horizontal Scaling

There are two ways for horizontal scaling in Mendix. In Mendix 5.15+ you can use sticky sessions or starting with Mendix 6 you can start Cluster Support (BETA). See below on how to activate both these settings.

Things to keep in mind when scaling horizontally

When you make changes to your domain model, the Mendix Runtime will need to synchronize data model changes with the database on startup. This will only happen on instance 0. The other instances will wait until the database is fully synchronized. This is determined via the CF_INSTANCE_INDEX environment variable. This is a built-in variable in Cloud Foundry, you do not need to set it yourself. If the environment variable is not present (this is the case older Cloud Foundry versions) every instance will attempt to synchronize the database. A warning containing the text CF_INSTANCE_INDEX environment variable not found will be printed in the log.

Enabling Sticky Sessions

Scheduled events will also only be executed on instance 0, see the section Configuring Scheduled Events. If you want to enable sticky sessions, the only change that is needed is to set the environment variable ENABLE_STICKY_SESSIONS to true. This will replace the Mendix session cookie name from XASSESSIONID to JSESSIONID which will trigger sticky session detection in the Cloud Foundry http router. Watch out: custom login code might break if it still injects the XASSESSIONID cookie.

Configuring Cluster Support (BETA feature for Mendix 6)

From Mendix 6 onwards it is possible to configure clustering support. With clustering support it is possible to run multiple instances of your application to achieve High Availability. Clustering support can be enabled by setting the environment variable CLUSTER_ENABLED to true.

To optimize performance it is possible to choose for REDIS as State Storage. To use that, add the RedisCloud service to your application and configure Mendix to use REDIS for State Storage by setting the environment variable CLUSTER_STATE_IMPLEMENTATION to redis. In case your selected REDIS service has limited connections available, configure the maximum amount of connections that REDIS can allocate per Mendix Business Server instance by setting the environment variable CLUSTER_STATE_REDIS_MAX_CONNECTIONS to the amount of connections available in your plan divided by the amount of instances you want to run.

NOTE: Clustering support is a BETA feature and as such not supported by Mendix for production usage. Settings and implementations may be changed in future releases!

NOTE: Enabling clustering support will automatically disable sticky sessions

Offline buildpack settings

If you are running Cloud Foundry without a connection to the Internet, you should specify an on-premises web server that hosts Mendix Runtime files and other buildpack resources. You can set the endpoint with the following environment variable:

BLOBSTORE: https://my-intranet-webserver.my-company.com/mendix/

The preferred way to set up this on-premises web server is as a transparant proxy to https://cdn.mendix.com/. This prevents manual work by system administrators every time a new Mendix version is released.

Alternatively you can make the required mendix runtime files mendix-VERSION.tar.gz available under BLOBSTORE/runtime/. You should also make the Java version available on /mx-buildpack/oracle-java8u45-jdk_8u45_amd64.deb available under BLOBSTORE/mx-buildpack/. The original files can be downloaded from https://cdn.mendix.com/.

Certificate Management

To import Certificate Authorities (CAs) into the Java truststore, use the CERTIFICATE_AUTHORITIES environment variable.

The contents of this variable should be a concatenated string containing a the additional CAs in PEM format that are trusted. Example:

Please note, these are two internal Mendix CAs which you should not actually add to your trust store.

Monitoring Tools

New Relic

To enable New Relic, simply bind a New Relic service to this app and settings will be picked up automatically. Afterwards you have to restage your application to enable the New Relic agent.

AppDynamics

To enable AppDynamics, configure the following environment variables:

APPDYNAMICS_CONTROLLER_PORT
APPDYNAMICS_CONTROLLER_SSL_ENABLED
APPDYNAMICS_CONTROLLER_HOST_NAME
APPDYNAMICS_AGENT_APPLICATION_NAME
APPDYNAMICS_AGENT_ACCOUNT_NAME
APPDYNAMICS_AGENT_ACCOUNT_ACCESS_KEY
APPDYNAMICS_AGENT_NODE_NAME *
APPDYNAMICS_AGENT_TIER_NAME

* The APPDYNAMICS_AGENT_NODE_NAME environment variable will be appended with the value of the CF_INSTANCE_ID variable. If you use my-app for APPDYNAMICS_AGENT_NODE_NAME, the AppDynamics agent will be configured as my-app-0 for instance 0 and my-app-1 for instance 1, etc.

If you have any environment variable that starts with APPDYNAMICS_, the AppDynamics Java Agent will be configured for your application. At the moment only agent version 4.1.7.1 is available. After configuring these environment variables, restage your app for the agent to be enabled.

Please note that AppDynamics requires Mendix 6.2 or higher.

Data Snapshots

If you want to enable initializing your database and files from an existing data snapshot included in the MDA, set USE_DATA_SNAPSHOT to true.

Logging and Debugging

To debug the code of the buildpack itself, set the BUILDPACK_XTRACE environment variable to true.

App log levels

From Mendix 6 onwards it is possible to configure log levels using environment variables. This allows getting a better insight in the behavior of your Mendix app. Configuring environment variables happens by adding one or more environment variables starting with the name LOGGING_CONFIG (the part of the name after that is not relevant and only used to distinguish between multiple entries if necessary). Its value should be valid JSON, in the format:

{
  "LOGNODE": "LEVEL",
  "PREFIX\*": "LEVEL",
}

You can see the available Log Nodes in your application in the Mendix Modeler. The level should be one of:

CRITICAL
ERROR
WARNING
INFO
DEBUG
TRACE

Enabling the Mendix Debugger

You can enable the Mendix Debugger by setting a DEBUGGER_PASSWORD environment variable. This will enable and open up the debugger for the lifetime of this process and is to be used with caution. The debugger is reachable on https://DOMAIN/debugger/. You can follow the second half of this How To to connect with the Mendix Business Modeler. To stop the debugger, unset the environment variable and restart the application.

Contributing

Make sure your code complies with pep8 and that no pyflakes errors/warnings are present.

Rebase your git history in such a way that each commit makes one consistent change. Don't include separate "fixup" commits later on.

bvanreeven/cf-mendix-buildpack