diff --git a/content/en/docs/deployment/docker-deploy/docker-pad.md b/content/en/docs/deployment/docker-deploy/docker-pad.md index 7f028b4d449..a1ff49f6784 100644 --- a/content/en/docs/deployment/docker-deploy/docker-pad.md +++ b/content/en/docs/deployment/docker-deploy/docker-pad.md @@ -21,62 +21,113 @@ 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 + +To create a Portable Package from your Mendix app, perform the following steps: + +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**. -1. Generate the application files. For more information, see [Portable App Distribution](/developerportal/deploy/portable-app-distribution-deploy/). +The Portable Package is saved to the following location: `/releases/.zip`. - These files are the core of your Mendix application and are ready to be included in a Docker image. +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 - 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. +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. # It is based on the configuration named Default. + # Start from an JAVA base image, as the Portable Package contains all necessary dependencies FROM eclipse-temurin:21-jdk - # Set working directory + # Set the working directory to /app WORKDIR /mendix - # Copy Mendix app files into the image + # Copy the contents of the Portable Package to the /app directory in the image COPY ./app ./app COPY ./bin ./bin COPY ./etc ./etc COPY ./lib ./lib - # Environment variables (optional) + # Set environment variables (optional) ENV MX_LOG_LEVEL=info ENV M2EE_ADMIN_PASS=${M2EE_ADMIN_PASS} - # Expose ports + # Expose port 8080 for the Mendix Runtime and port 8090 for the Mendix Runtime admin interface EXPOSE 8090 EXPOSE 8080 - # Start command + # Set the start script to the Mendix Runtime execute 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. + +3. Build the Docker image by using the following command: `docker build -t : -f build/docker/Dockerfile`, where: + + * `` and `` - Indicate your required 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, perform the following steps: -2. Build the Docker image by running a command like the following: `docker build -t mx/project:latest -f build/docker/Dockerfile`, where: +1. Log in to your container registry by running the following command: `docker login `. +2. Tag the Docker image with the registry URL by running the following command: `docker tag : /:`. +3. Push the Docker image to the registry by running the following command: `docker push /:`. - * `-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. +### Deploying the Docker Image - * `-f build/docker/Dockerfile` - Specifies the path to your Dockerfile. +Once the Docker image is available in your container registry, you can deploy it to your target environment by performing the following steps: -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: +1. Pull the Docker image from your container registry by running the following command: `docker pull /:`, replacing ``, ``, and `` with the appropriate values for your Docker image. +2. Optional: Configure the container. + + The Portable App Distribution container can be configured to suit your deployment environment and requirements. You can do this in the `etc` [configuration folder](/developerportal/deploy/portable-apps-distribution/reference/#folder-structure). You can also apply the configuration 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. + +3. Run the container by using the command `docker run --rm -it -p 8080:8080 -e M2EE_ADMIN_PASS= /:`, 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=` - Ensure that you set your admin password here. - * `mx/project:latest` - Refers to the image that you built. + * `/:` - 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. +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 @@ -116,4 +167,70 @@ 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} + +You can configure the Mendix Runtime by using environment variables. For example, the following environment variables are supported: + +| Environment Variable | Description | +| --- | --- | +| `DATABASE_TYPE` | The type of the database (for example, PostgreSQL, MySQL)| +| `DATABASE_HOST` | The host name and port of the database server | +| `DATABASE_NAME` |The name of the database | + +For more information, see [Runtime Customization](/refguide/custom-settings/#introduction). + +## Configuration File {#config-file} + +Alternatively, you can configure the Mendix Runtime by 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 configuration path: + +`docker run --rm -it -p 8080:8080 -e M2EE_ADMIN_PASS= /: \ -v host_path/config.conf:container_path/config.conf` + +You must also mount the volume so that Docker can find it. + +## Logging + +The Mendix Runtime logs to a 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.