Portable App Distribution for Docker

Introduction

This guide provides a walkthrough for deploying your Mendix application using Portable App Distribution with Docker. This approach is particularly useful for containerized environments, and can significantly ease your CI/CD setup.

Benefits of Portable App Distribution

Portable App Distribution revolutionizes the way in which Mendix applications are packaged and delivered. This innovative approach bundles your application code with all its necessary dependencies into a single, self-contained, and runnable artifact. This greatly simplifies the deployment of Mendix applications, whether you are targeting on-premise infrastructure or modern containerized environments like Docker, making the entire process more efficient and seamless.

The ability to generate a Portable App Distribution with a single build command means that creating a Docker-ready artifact becomes a streamlined process, making the overall integration into existing Docker-based CI/CD pipelines more efficient and less prone to errors.

Portable App Distribution offers a more agile, user-centric, and efficient deployment ecosystem, empowering customers with greater control over their Docker deployments and simplifying the internal deployment processes.

Deploying an App with Portable App Distribution

The Portable App Distribution feature in Mendix Studio Pro provides you with the necessary application files to build a Docker image. It packages your Mendix application as a self-contained distribution, ready for integration into your Docker environment.

To deploy your app to Docker, perform the following steps:

1. Generate the application files. For more information, see Portable App Distribution.

   These files are the core of your Mendix application and are ready to be included in a Docker image.

   The following is an example Dockerfile that incorporates them. You must create this Dockerfile yourself and place it alongside the application files generated by the Portable App Distribution. The COPY commands in the example below assumes that the app, bin, etc, and lib directories are in the same location as your Dockerfile.

   # This file provides an example on how to start the runtime in Docker.
   # It is based on the configuration named Default.
   
   FROM eclipse-temurin:21-jdk
   
   # Set working directory
   WORKDIR /mendix
   
   # Copy Mendix app files into the image
   COPY ./app ./app
   COPY ./bin ./bin
   COPY ./etc ./etc
   COPY ./lib ./lib
   
   # Environment variables (optional)
   ENV MX_LOG_LEVEL=info
   ENV M2EE_ADMIN_PASS=${M2EE_ADMIN_PASS}
   
   # Expose ports
   EXPOSE 8090
   EXPOSE 8080
   
   # Start command
   CMD ["./bin/start", "etc/Default"]

2. Build the Docker image by running a command like the following: docker build -t mx/project:latest -f build/docker/Dockerfile, where:

   • -t mx/project:latest - Tags your image as mx/project with the label latest. You can customize this to your project's name and version.

   • -f build/docker/Dockerfile - Specifies the path to your Dockerfile.

3. Start your Mendix application in a Docker container by running a command like the following: docker run --rm -it -p 8080:8080 -e M2EE_ADMIN_PASS=<your password> mx/project:latest, where:

   • --rm - Automatically removes the container when it exits.
   • -it - Runs the container in interactive mode and allocates a pseudo-TTY.
   • -p 8080:8080 - Maps port 8080 on your host machine to port 8080 inside the container, allowing you to access your app.
   • -e M2EE_ADMIN_PASS=<yourPassword> - Ensure that you set your admin password here.
   • mx/project:latest - Refers to the image that you built.

You can view your running Mendix application at localhost:8080. To stop the application, press Ctrl-C in your terminal.

Docker Compose for Multi-Container Setups

For more complex setups involving multiple Docker containers, or for simpler local testing purposes, you can use Docker Compose. It allows you to define and run multi-container Docker applications.

The following is an example of a docker-compose.yaml file that sets up your Mendix application with an HSQLDB for local testing. This example assumes you have the Portable App Distribution files (app, bin, etc, lib) in a parent directory relative to your docker-compose.yaml file.

# This file provides an example on how to start the runtime with HSQLDB.
# This setup is intended for local testing only.
# It is based on the configuration named Default.

services:
  mendix-app:
    image: eclipse-temurin:21-jdk
    container_name: mendix-app
    working_dir: /mendix
    volumes:
      - ../app:/mendix/app
      - ../bin:/mendix/bin
      - ../etc:/mendix/etc
      - ../lib:/mendix/lib
    environment:
      - MX_LOG_LEVEL=info
      - M2EE_ADMIN_PASS=${M2EE_ADMIN_PASS}
    ports:
      - "8090:8090"
      - "8080:8080"
    command: ["./bin/start", "etc/Default"]

Running with Docker Compose

To use this Docker Compose configuration, perform the following steps:

1. Set your admin port password in the M2EE_ADMIN_PASS variable within your environment, or directly in the docker-compose.yaml file.
2. Navigate to the directory containing your docker-compose.yaml file
3. Run a command like the following: docker compose -f docker_compose/Default.yaml up

This example assumes that your configuration is named Default.