diff --git a/content/en/docs/deployment/docker-deploy/docker-pad.md b/content/en/docs/deployment/docker-deploy/docker-pad.md index 7f028b4d449..f23051638af 100644 --- a/content/en/docs/deployment/docker-deploy/docker-pad.md +++ b/content/en/docs/deployment/docker-deploy/docker-pad.md @@ -21,19 +21,50 @@ Portable App Distribution revolutionizes the way in which Mendix applications ar 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. +The Portable App Distribution feature allows you to package and deploy Mendix apps without relying on the Mendix Cloud or a Mendix Operator. This is particularly useful for the following use cases: + +* Air-gapped environments where internet access is restricted or unavailable +* Private cloud deployments where you manage your own infrastructure +* Full control scenarios where you need complete ownership of the deployment pipeline + +Docker provides a consistent and reproducible environment for running Mendix apps, making it ideal for cloud-native and containerized deployments. + 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. +## Prerequisites + +Before you begin, ensure you have the following: + +* Mendix Studio Pro version 11.19, 11.6.5, or above +* A Mendix app that you want to deploy +* Docker installed on your system (for building and running Docker images) +* Access to a container registry (for pushing and pulling Docker images) + ## 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: +To deploy your app to Docker, you must create a Portable App Distribution Package, build a Docker image, and then deploy the Docker image (including optionally pushing it to a container registry. For more information, refer to the sections below. + +### Creating a Portable App Distribution Package -1. Generate the application files. For more information, see [Portable App Distribution](/developerportal/deploy/portable-app-distribution-deploy/). +To create a Portable Package from your Mendix app, perform the following steps: - These files are the core of your Mendix application and are ready to be included in a Docker image. +1. Open your app in Studio Pro. +2. Go to **App** > **Create Deployment Package**. +3. In the **Create Deployment Package** dialog, select **Portable package**. +4. Click **OK**. - 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. +The Portable Package is saved to the following location: `/releases/.zip`. + +For more information about Portable Packages, see [Portable App Distribution](/developerportal/deploy/portable-app-distribution-deploy/). Files included in the Portable Package are the core of your Mendix application and are ready to be included in a Docker image. + +### Building a Docker Image + +To build a Docker image from the Portable Package, perform the following steps: + +1. Extract the Portable Package to a directory of your choice. +2. Create a Dockerfile in the extracted directory with contents like the following. ```text # This file provides an example on how to start the runtime in Docker. @@ -61,20 +92,71 @@ To deploy your app to Docker, perform the following steps: # Start command CMD ["./bin/start", "etc/Default"] ``` + 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 above assume that the `app`, `bin`, `etc`, and `lib` directories are in the same location as your Dockerfile. + +{{% alert color="info" %}} Explanation +FROM eclipse-temurin:21-jdk – Starts from an JAVA base image, as the Portable Package contains all necessary dependencies. + +COPY . /app – Copies the contents of the Portable Package to the /app directory in the image. + +WORKDIR /mendix – Sets the working directory to /app. + +EXPOSE 8080 – Exposes port 8080 for the Mendix Runtime. + +EXPOSE 8090 – Exposes port 8090 for the Mendix Runtime admin interface. + +CMD ["./bin/start", "etc/Default"] – Sets the start script to the Mendix Runtime execute.{{% /alert %}} + + +3. Build the Docker image using the following command: + + +`docker build -t : -f build/docker/Dockerfile` + +* Replace `` and `` with your desired image name and version tag (for example, my-mendix-app:1.0.0). +* `-f build/docker/Dockerfile` - Specifies the path to your Dockerfile. + +### Optional: Pushing the Docker Image + +To push the Docker image to a container registry, follow these steps: + +Log in to your container registry: + +`docker login ` + +Tag the Docker image with the registry URL: -2. Build the Docker image by running a command like the following: `docker build -t mx/project:latest -f build/docker/Dockerfile`, where: +`docker tag : /:` - * `-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. +Push the Docker image to the registry: - * `-f build/docker/Dockerfile` - Specifies the path to your Dockerfile. +`docker push /:` -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= mx/project:latest`, where: +### Deploying the Docker Image - * `--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=` - Ensure that you set your admin password here. - * `mx/project:latest` - Refers to the image that you built. +Once the Docker image is available in your container registry, you can deploy it to your target environment using the steps below. + +Step 1: Pull the Docker Image +Pull the Docker image from your container registry: + +`docker pull /:` +Replace , , and with the appropriate values for your Docker image. + +Step 2: Configure the Container (optional) +The Portable App Distribution container can be configured to suit your deployment environment and requirements. This can be done at the configuration `etc` folder. (https://docs.mendix.com/developerportal/deploy/portable-apps-distribution/reference/#folder-structure ) +Configuration can also be applied either through **environment variables** or a **configuration file**, giving you flexibility depending on your setup and preferences. Both approaches support the same set of runtime settings, so you can choose whichever method best fits your workflow. + +For more information, see the [Environment Variables](#env-variables) and [Configuration File](#config-file) sections below. + +Step 3: Run the Container +Run the container using the following command: + + `docker run --rm -it -p 8080:8080 -e M2EE_ADMIN_PASS= /:` +* --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= - Ensure that you set your admin password here. +* /:- 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. @@ -116,4 +198,72 @@ To use this Docker Compose configuration, perform the following steps: 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. \ No newline at end of file +This example assumes that your configuration is named Default. + +## Environment Variables {#env-variables} + +The Mendix Runtime can be configured using environment variables. A sample of the following environment variables are supported: + +| Environment Variable | Description | +|----------------------|-------------| +|`DATABASE_TYPE`|The type of the database (e.g., PostgreSQL, MySQL)| +|`DATABASE_HOST`|The hostname of the database server and the port of the database server| +|`DATABASE_NAME`|The name of the database| + +From more information for more information, see https://docs.mendix.com/refguide/custom-settings/#introduction + +## Configuration File {#config-file} + +Alternatively, you can configure the Mendix Runtime using a configuration file. The configuration file is a JSON file that contains the same settings as the environment variables. + +### Example Configuration File + +```json +{ + "DatabaseType": "PostgreSQL", + "DatabaseHost": "localhost:5432", + "DatabaseName": "mendix", + "DatabaseUserName": "mendix", + "DatabasePassword": "mendix", + "AdminPassword": "Admin1234!", + "RuntimePort": 8080, + "RuntimeAdminPort": 8090 +} +```` + +### Using the Configuration File + +To use the configuration file, you can upload the configuration file to the path of the configuration path: + +`docker run --rm -it -p 8080:8080 -e M2EE_ADMIN_PASS= /: \ + -v host_path/config.conf:container_path/config.conf` + +You need to mount the volume so that Docker can find it. + +## Logging + +The Mendix Runtime logs to standard output by default. You can configure the log level using the MX_LOG_LEVEL environment variable. + +The following log levels are supported (in order of verbosity): + +|Log Level|Description| +|---------|-----------| +|`TRACE`|Most verbose — logs all internal operations| +|`DEBUG`|Detailed diagnostic information| +|`INFO`|General operational messages (default)| +|`WARNING`|Potentially harmful situations| +|`ERROR`|Error events that may still allow the app to continue| +|`CRITICAL`|Severe errors that may cause the app to stop| + + +## Health Checks + +The Mendix Runtime exposes health check endpoints that can be used to monitor the status of your app: + +|EndPoint|Description| +|--------|-----------| +|`/health`|Returns the overall health status of the app| +|`/health/live`|Returns the liveness status — indicates if the app is running| +|`/health/ready`|Returns the readiness status — indicates if the app is ready to serve traffic| + +These endpoints are especially useful when integrating with orchestration platforms such as Kubernetes, which rely on liveness and readiness probes to manage container lifecycle.