Merge pull request #10935 from mendix/kk-pad

Portable App Distribution

Author: katarzyna-koltun-mx

content/en/docs/deployment/docker-deploy/_index.md

@@ -1,73 +1,26 @@
 ---
 title: "Docker"
-url: /developerportal/deploy/docker-deploy/
+url: /developerportal/deploy/docker/
 weight: 60
-description: "Describes how to deploy using a Docker image."
-#If moving or renaming this doc file, implement a temporary redirect and let the respective team know they should update the URL in the product. See Mapping to Products for more details.
+description: "Describes how to deploy your Mendix app to a Docker environment."
+no_list: false 
+description_list: true
 ---
 
 ## Introduction
 
-Docker is an open source container technology. With Mendix, you can use it for simple deployments, particularly when running local or development versions of your app. However, it lacks some scaling and integration features.
+This section describes how to deploy your Mendix app to a Docker environment.
 
-The Docker Buildpack simplifies the creation of Docker images locally, but it falls short in terms of running, managing, and operating them effectively compared to the capabilities offered by Mendix on Kubernetes. Leveraging Mendix on Kubernetes means entrusting the Mendix Operator to automate these essential tasks whenever Kubernetes handles your containers. The following diagram illustrates the disparity between Docker Buildpack and Mendix Operator:
+## Docker Deployment Options
 
-{{< figure src="/attachments/deployment/docker-deploy/dockerbuildpack-vs-mxoperator.png" class="no-border" >}}
+Mendix offers two options for Docker deployments: Portable App Distribution or the Docker Buildpack.
 
-{{% alert color="info" %}}
-Mendix suggests that, if you are planning to deploy to your own cloud platform at scale, a better solution for production apps is to use [Mendix on Kubernetes](/developerportal/deploy/private-cloud/). This provides you with structured and tested solutions for integrating with your own cloud infrastructure using comprehensive, automated, native functions, avoiding the need to create your own processes from scratch.
-{{% /alert %}}
+### Portable App Distribution
 
-This page explains how to build a Docker image from your Mendix App. Every time you make changes to your app, you must create a new Docker image that can be pushed through the different stages of your application pipeline.
+[Portable App Distribution](/developerportal/deploy/portable-app-distribution-deploy/) allows users to generate their portable app with a single MxBuild command. It requires fewer manual steps than the Docker Buildpack, simpler environment configuration, and no `rootfs` preparation. Running Portable App Distribution can take as little as 3-6 minutes (the time may vary based on the application's size and complexity).
 
-This how-to teaches you how to do the following:
+### Docker Buildpack
 
-* Build the image
-* Push the image to a registry
+The Docker Buildpack offers custom `rootfs` configuration, but requires multiple build steps, a more complex setup process, and a longer total build time (at least 14-25 minutes).
 
-## Prerequisites
-
-Before starting these instructions, make sure you have completed the following prerequisites:
-
-* Download the latest version of [Mendix Studio Pro](https://marketplace.mendix.com/link/studiopro/) from the *Mendix Marketplace*
-* Install Docker from the [Docker site](https://docs.docker.com/engine/installation/)
-* Download the [Mendix Docker Buildpack](https://github.com/mendix/docker-mendix-buildpack)
-
-## Building the Image
-
-To build the Docker image, follow these steps:
-
-1. Install Docker on your computer.
-2. Restart the computer to ensure that you have been granted access to Docker.
-3. Unzip the buildpack into a location of your choice.
-4. Open the **Command Prompt** and navigate to the folder where you unzipped the buildpack. 
-5. Open your app in Studio Pro and select the menu option **App** > **Show App Directory in Explorer**:
-
-    {{< figure src="/attachments/deployment/docker-deploy/create-deployment-package.png" class="no-border" >}}
-
-6. Copy the project folder and all its subfolders to the unzipped docker build folder. The project folder needs to be in the same folder as the Docker file, otherwise Docker cannot access it.
-7. Execute the following command:
-
-    ```bash
-    docker build --build-arg BUILD_PATH="{relative-mendix-project-location}" -t {image name} .
-    ```
-
-    **{relative-mendix-project-location}** is the BUILD_PATH which indicates where the application model is located. It is the directory where your .MPR file is located after you copied the project into the docker build folder. If you do not specify it, it defaults to `./project`.
-
-    A successful build will resemble the output shown below:
-
-    {{< figure src="/attachments/deployment/docker-deploy/build-image.png" class="no-border" >}}
-
-{{% alert color="info" %}}
-You can find much more information and links to relevant Docker documentation in the [Mendix Docker Buildpack](https://github.com/mendix/docker-mendix-buildpack) GitHub repository.
-{{% /alert %}}
-
-## Pushing the Image
-
-A new Docker image has been created with the name (`{image name}`) you gave it. You can see the image by using the command `docker images`.
-
-Next, you need to push the image to a registry. This can be a public registry or your own. To push it to your own registry, use the command `docker push {image name}`.
-
-## Read More
-
-* [How to Run a Mendix Docker Image](/developerportal/deploy/run-mendix-docker-image/)
+## Documents in This Section

content/en/docs/deployment/docker-deploy/docker-buildpack.md

@@ -0,0 +1,88 @@
+---
+title: "Docker Buildpack"
+url: /developerportal/deploy/docker-deploy/
+weight: 60
+description: "Describes how to deploy using a Docker image using a Docker Buildpack."
+#If moving or renaming this doc file, implement a temporary redirect and let the respective team know they should update the URL in the product. See Mapping to Products for more details.
+---
+
+## Introduction
+
+This page explains how to build a Docker image from your Mendix App using a Docker buildpack. Every time you make changes to your app, you must create a new Docker image that can be pushed through the different stages of your application pipeline.
+
+This how-to teaches you how to do the following:
+
+* Build the image
+* Push the image to a registry
+
+## Prerequisites
+
+Before starting these instructions, make sure you have completed the following prerequisites:
+
+* Download the latest version of [Mendix Studio Pro](https://marketplace.mendix.com/link/studiopro/) from the *Mendix Marketplace*
+* Install Docker from the [Docker site](https://docs.docker.com/engine/installation/)
+* Download the [Mendix Docker Buildpack](https://github.com/mendix/docker-mendix-buildpack)
+
+## Compatibility
+
+Mendix is compatible with Docker hosts as long as there are compatible database services like PostgreSQL, RDS, or Azure SQL. External file store support can be set up with Amazon S3 or Azure Blob store.
+
+## Building the Image
+
+To build the Docker image, follow these steps:
+
+1. Install Docker on your computer.
+2. Restart the computer to ensure that you have been granted access to Docker.
+3. Unzip the buildpack into a location of your choice.
+4. Open the **Command Prompt** and navigate to the folder where you unzipped the buildpack. 
+5. Open your app in Studio Pro and select the menu option **App** > **Show App Directory in Explorer**:
+
+    {{< figure src="/attachments/deployment/docker-deploy/create-deployment-package.png" class="no-border" >}}
+
+6. Copy the project folder and all its subfolders to the unzipped docker build folder. The project folder needs to be in the same folder as the Docker file, otherwise Docker cannot access it.
+7. Execute the following command:
+
+    ```bash
+    docker build --build-arg BUILD_PATH="{relative-mendix-project-location}" -t {image name} .
+    ```
+
+    **{relative-mendix-project-location}** is the BUILD_PATH which indicates where the application model is located. It is the directory where your .MPR file is located after you copied the project into the docker build folder. If you do not specify it, it defaults to `./project`.
+
+    A successful build will resemble the output shown below:
+
+    {{< figure src="/attachments/deployment/docker-deploy/build-image.png" class="no-border" >}}
+
+{{% alert color="info" %}}
+You can find much more information and links to relevant Docker documentation in the [Mendix Docker Buildpack](https://github.com/mendix/docker-mendix-buildpack) GitHub repository.
+{{% /alert %}}
+
+## Pushing the Image
+
+A new Docker image has been created with the name (`{image name}`) you gave it. You can see the image by using the command `docker images`.
+
+Next, you need to push the image to a registry. This can be a public registry or your own. To push it to your own registry, use the command `docker push {image name}`.
+
+## Running the Mendix Docker Image
+
+To start the container, you must provide the container with the password in order to create an administrative account for your Mendix application's `ADMIN_PASSWORD`
+and `DATABASE_ENDPOINT`, as you can see in this example:
+
+```shell
+docker run -it \
+  -e ADMIN_PASSWORD=Password1! \
+  -e DATABASE_ENDPOINT=postgres://username:password@host:port/mendix \
+  mendix/mendix-buildpack:v1.2  
+```
+
+This is an example for Microsoft SQL Server:
+
+```powershell
+docker run -it \
+  -e ADMIN_PASSWORD=Password1! \
+  -e DATABASE_ENDPOINT=sqlserver://username:password@host:port/mendix \
+  mendix/mendix-buildpack:v1.2  
+```
+
+## Read More
+
+* [Mendix Docker Buildpack](https://github.com/mendix/docker-mendix-buildpack)

content/en/docs/deployment/docker-deploy/docker-pad.md

@@ -0,0 +1,119 @@
+---
+title: "Portable App Distribution for Docker"
+url: /developerportal/deploy/docker-deploy-pad/
+weight: 20
+description: "Describes how to deploy using a Docker image by using Portable App Distribution."
+---
+
+## Introduction
+
+This guide provides a walkthrough for deploying your Mendix application using [Portable App Distribution](/developerportal/deploy/portable-app-distribution-deploy/) with Docker. This approach is particularly useful for containerized environments, and can significantly ease your CI/CD setup.
+
+{{% alert color="info" %}}
+This document is not an official Mendix implementation, or a substitute for recommended production deployment strategies. For more features, such as app management or governance, we suggest using [Mendix on Kubernetes](/developerportal/deploy/private-cloud/) or [Mendix on Azure](/developerportal/deploy/mendix-on-azure/), which offer a structured, tested experience with cloud infrastructure. 
+
+For information about the scope of support, see [Support for Different Deployment Strategies](/support/deployment-strategy-support/).
+{{% /alert %}}
+
+## 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](/developerportal/deploy/portable-app-distribution-deploy/).
+
+    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.
+
+    ```text
+    # 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.
+
+```yaml
+# 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.