Enhance Docker deployment documentation for Mendix apps

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: `<your-project-folder>/releases/<XYZ_portable_YYYYMMDD_hhmm>.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 <your-image-name>:<tag> -f build/docker/Dockerfile`
+
+* Replace `<your-image-name>` and `<tag>` 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 <your-registry>`
+
+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 <your-image-name>:<tag> <your-registry>/<your-image-name>:<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 <your-registry>/<your-image-name>:<tag>`
 
-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:
+### 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=<yourPassword>` - 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 <your-registry>/<your-image-name>:<tag>`
+Replace <your-registry>, <your-image-name>, and <tag> 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=<your password> <your-registry>/<your-image-name>:<tag>`
+* --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.
+* <your-registry>/<your-image-name>:<tag>- 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.
+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=<your password> <your-registry>/<your-image-name>:<tag> \
+ -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.