Add documentation for the private PDF Document Generation service

content/en/docs/marketplace/platform-supported-content/modules/document-generation.md → content/en/docs/marketplace/platform-supported-content/modules/document-generation/_index.md

@@ -19,17 +19,21 @@ The [PDF Document Generation](https://marketplace.mendix.com/link/component/2115
 
 ### Limitations {#limitations}
 
-* Currently, PDF is the only supported document export format.
-* For deployment, currently we support [Mendix Cloud](/developerportal/deploy/mendix-cloud-deploy/), [Mendix Cloud Dedicated](/developerportal/deploy/mendix-cloud-deploy/), [Mendix for Private Cloud Connected](/developerportal/deploy/private-cloud/), and [On-Premises](/developerportal/deploy/on-premises-design/). Other deployment scenarios will be supported at a later stage.
-
+* PDF is the only supported document export format.
+* For deployment, we support: 
+
+    * [Mendix Cloud](/developerportal/deploy/mendix-cloud-deploy/)
+    * [Mendix Cloud Dedicated](/developerportal/deploy/mendix-cloud-deploy/)
+    * [Mendix for Private Cloud Connected](/developerportal/deploy/private-cloud/)
+    * [On-Premises](/developerportal/deploy/on-premises-design/)
+    * A privately hosted Docker containerized PDF Document Generation service. It is available starting with module versions 1.11.0 for Studio Pro 9 and 2.1.0 for Studio Pro 10. For more information, refer to [Private PDF Document Generation Service](/appstore/modules/private-document-generation-service/).
     {{% alert color="info" %}}For all deployment types except for on-premises, we only support apps that allow bi-directional communication with the PDF Service in Mendix Cloud.{{% /alert %}}
-
 * The maximum file size is 25 MB per document. If your document exceeds this limit, the action will result in an exception. We recommend compressing high-resolution images to reduce their file size.
-* If your app is configured to [restrict access for incoming requests](/developerportal/deploy/access-restrictions/) using client certificates, our cloud service will not be able to reach your app and the module will not work properly.
+* If your app is configured to [restrict access for incoming requests](/developerportal/deploy/access-restrictions/) using client certificates, our cloud service will not be able to reach your app, and the module will not work properly.
 * If your app uses a custom domain, you must configure a custom SSL/TLS domain certificate signed by a trusted public authority, including all intermediate certificates if applicable. Self-signed certificates will cause the service to fail. For more information, see [Obtaining a new signed certificate](/developerportal/deploy/custom-domains/#obtaining-a-new-signed-certificate).
 * We use a fixed 30 second timeout for the page to finish loading and rendering. A timeout exception is thrown if the page content did not finish loading within 30 seconds.
 * Widgets or add-ons for your `index.html` file that perform long polling network requests are not supported. The document generation service waits until there are no more pending network requests.
-* Some widgets, such as the [Charts](/appstore/widgets/charts/) widget, might be rendered inconsistently in the generated PDF due to factors like animation.
+* Some widgets, such as [Charts](/appstore/widgets/charts/), might be rendered inconsistently in the generated PDF due to factors like animation.
 * Complex documents (for example, large tables) may run into memory limitations, separate from the file size limitation. Try to reduce the number of widgets inside repeatable widgets as much as possible.
 * We currently do not enforce strict rate limits. However, take into account the following guidelines:
     * Only set the `Wait for result` parameter to *true* for direct user actions. Do not set it to *true* for batch processing. Under heavy load, requests that wait for the result may fail due to strict timeout limitations.
@@ -41,8 +45,8 @@ The [PDF Document Generation](https://marketplace.mendix.com/link/component/2115
 * Setting the microflow property **Apply entity access** to *Yes* does not have any effect on the `Generate PDF from page` action. Regardless of the **Apply entity access** setting, the action does not require *Create* or *Write* access rights for the `FileDocument` object that gets created.
 * The `System.Owner` association is currently not set to the user which has run the microflow. Instead, the user that is configured for the `Generate as user` property of the `Generate PDF from page` action is used to set the association.
 * For local development, we use the Chrome or Chromium executable that is available on the development machine. Even though we have not observed these yet, there might be minor differences in PDF output locally versus when using the cloud service.
-* The access (and refresh) tokens used to secure requests to the cloud service are stored unencrypted in the app database. No user roles have read access to these tokens and all communication with the cloud service is encrypted by requiring HTTPS. However, do consider this when sharing a backup of the database with other developers. We will introduce encryption at a later stage.
-* If you have the [Application Performance Monitor (APM)](/appstore/partner-solutions/apd/) or [Application Performance Diagnostics (APD)](/appstore/partner-solutions/apd/) add-on enabled in your app, or set the log level of the **Services** log node to *Trace*, the PDF Document Generation module will not be able to generate documents when used in Mendix Cloud. This limitation is only applicable for apps built in Mendix 9.24.5 and below and Mendix 10.0.0.
+* The access and refresh tokens used to secure requests to the cloud service are stored unencrypted in the app database. No user roles have read access to these tokens, and all communication with the cloud service is encrypted by requiring HTTPS. However, do consider this when sharing a backup of the database with other developers. We will introduce encryption at a later stage.
+* If you have the [Application Performance Monitor (APM)](/appstore/partner-solutions/apd/) or [Application Performance Diagnostics (APD)](/appstore/partner-solutions/apd/) add-on enabled in your app, or the log level of the **Services** log node set to *Trace*, the PDF Document Generation module will not be able to generate documents when used in Mendix Cloud. This limitation is only applicable for apps built in Mendix 9.24.5 and below and Mendix 10.0.0.
 
 ### Dependencies
 

content/en/docs/marketplace/platform-supported-content/modules/document-generation/private-service.md

@@ -0,0 +1,124 @@
+---
+title: "Private PDF Document Generation Service"
+url: /appstore/modules/private-document-generation-service/
+description: "Describes the configuration and usage of the private PDF Document Generation service, which is used in combination with the PDF Document Generation module in the Marketplace."
+#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
+
+Mendix offers a public, Mendix-hosted PDF document generation service included with the [PDF Document Generation module](/appstore/modules/document-generation/). 
+
+In some cases, however, access to this public service is not available, such as for apps running in air-gapped environments. For these scenarios, Mendix offers a private PDF Document Generation service for Mendix apps. 
+
+### Features {#features}
+
+These are the main features of the private PDF Document Generation service:
+
+* It can run as a centralized service or as a container per app. 
+* It can run on any container infrastructure that supports Docker as the container runtime, such as Kubernetes, AWS ECS, etc.
+* It has no enforced rate limits. The actual rate limit depends on the resource configuration and usage of the container.
+* It has configurable limits for maximum file size and maximum page rendering time.
+
+### Limitations {#limitations}
+
+These are the limitations of using the private PDF Document Generation service:
+
+* Setup, management, and monitoring of the service is your responsibility.
+* The service is open to all applications that can access it. If additional access restrictions are required, you need to set these up at the network level and configure them.
+* You cannot import custom certificate authorities. Apps that use a self-signed or internal certificate are only supported when you disable certificate validation in the service.
+* You are responsible for setting up a retry mechanism in the application to handle failures or timeouts of the service.
+
+### Prerequisites {#prerequisites}
+
+Before you start using the private PDF Document Generation service, make sure you meet these prerequisites:
+
+* You have a good understanding of how to run and manage Docker containers. 
+* You are familiar with the PDF Document Generation module. For more information, refer to [PDF Document Generation](/appstore/modules/document-generation/).
+* Your deployment environment needs to allow bidirectional communication between Mendix apps and the Docker containers running the private PDF Document Generation service.
+
+## Installation {#installation}
+
+The service can be set up in several ways, depending on the specific customer needs, such as the required isolation level and the scalability requirements. To install the service, make sure you review the following considerations and adapt your setup accordingly.
+
+### Required Resources
+
+The required resources depend on demand. For instance, to be able to generate 5 documents in parallel, we recommend the following as a minimum:
+
+* CPU: more than 2 CPU cores
+* Memory: more than 4096 MB of RAM
+
+### Installing the Service
+
+The following artifact is available for installing the service:
+
+* The Docker image for the PDF Document Generation service 
+
+#### Installing through Docker
+
+Follow these steps to install the service through Docker:
+
+1. Pull the Docker image using the following command: `docker pull private-cloud.registry.mendix.com/mendix/document-generation-service:<tag>`.
+2. Run the Docker container using the following command: `docker run -p 8085:8085 --name document-generation private-cloud.registry.mendix.com/mendix/document-generation-service:<tag>`. The `<tag>` component must be replaced with the version of the service, such as `1.0.0`. This creates a Docker container, which is exposed on port `8085`.
+
+### Isolation
+
+Requests share the same container resources, which has the following implications:
+
+* Requests in the same container could affect each other in terms of performance.
+* Container crashes could affect all requests being processed at the time of the crash.
+
+Requests in the same container are isolated at the browser level, using an incognito browser context per request.
+
+### Scalability
+
+You can scale the service in two ways:
+
+* Using vertical scaling, with a single container setup
+
+    * One container can serve multiple requests at a time, where requests are processed in parallel using an isolated browser context per request.
+    * The browser keeps running after processing a request.
+    * No load balancing is needed in case of a single container instance.
+
+* Using horizontal scaling, where multiple containers run in parallel
+
+    * Each container can serve multiple requests at a time.
+
+Running multiple container replicas requires additional load balancing, which is not provided by Mendix. You need to configure and use your own preferred load balancing tools, such as [Nginx](https://nginx.org/).
+
+## Configuration {#configuration}
+
+The service has several [configuration options](#configuration-options) for adapting to your specific needs.
+
+### Setting Configuration Values {#setting-configuration-values}
+
+The approach for setting configuration values depends on the installation type. Follow the applicable instructions described in the [Available Configuration Options](#configuration-options) table.
+
+#### Configuring through Docker
+
+When using Docker to run the image, add the configuration using the provided environment variables. An example of this is `docker run -p 8085:8085 -e MAX_DOCUMENT_SIZE=<value> --name document-generation private-cloud.registry.mendix.com/mendix/document-generation-service:<tag>`.
+
+### Available configuration options {#configuration-options}
+
+| Environment variable | Default value | Description |
+|----------------------|---------------|-------------|
+| `MAX_DOCUMENT_SIZE` | `25000000` (25 MB) | The maximum size for PDF documents generated using the service. When a PDF exceeds this file size, the request is aborted. |
+| `MAX_PAGE_RENDERING_TIME` | `30000` (30 seconds) | The maximum time to wait for the page to finish loading and rendering. If loading the page exceeds this time, a [Wait for Content](/appstore/modules/document-generation/#wait-for-content-exception) exception is sent to the module. |
+| `ACCEPT_INSECURE_CERTIFICATES` | `false` | <p> Allows the use of untrusted certificates, such as when using self-signed certificates.</p> <p> **Warning:** This disables certificate validation, and allows the use of invalid certificates. Be aware of any resulting security risks.</p> |
+
+## Configuring your Mendix Apps
+
+When you have the PDF Document Generation container running in your environment, you need to configure your Mendix apps to use the private service, as follows:
+
+* Make sure that you are using version 2.1.0 or higher of the PDF Document Generation module.
+* Configure the `DocumentGeneration.OverrideServiceType` constant to `Private`.
+* Configure the `DocumentGeneration.ServiceEndpoint` constant to point to the container address and port, such as `http://document-generation:8085`.
+* To generate your first document, follow the instructions in the module documentation [PDF Document Generation](/appstore/modules/document-generation/).
+
+{{% alert color="info" %}}You do not need to register your application when using a private service. In this case, it is therefore also not required to include the `Snip_AppRegistration` snippet in your app.{{% /alert %}}
+
+## Logging
+
+All application level errors are sent back to the module. Refer to [PDF Document Generation](/appstore/modules/document-generation/) for details. 
+
+Technical logs of the service are available at the container level. If you run multiple containers, logs are spread across them. We recommend to set up a centralized monitoring solution yourself.

content/en/docs/releasenotes/marketplace/general-marketplace.md

@@ -14,11 +14,17 @@ These release notes cover changes made to the [Mendix Marketplace](/appstore/).
 
 ## 2025
 
+### June 27, 2025
+
+#### New Features
+
+* The [PDF Document Generation](/appstore/modules/document-generation/) module now supports the use of [private PDF document generation service instances](/appstore/modules/private-document-generation-service/). This flexible solution is based on Docker, and is hosted and managed by you. It allows you to run your own version of the PDF Document Generation service with additional control and configuration options, and it specifically targets air-gapped apps, or tailored performance and data sharing requirements.
+
 ### June 25, 2025
 
-#### Mendix Data Loader Version 2.3.0
+#### New Features
 
-This version of [Mendix Data Loader](/appstore/modules/snowflake/mendix-data-loader/) allows you to configure a specific warehouse for your task, which is used as a compute resource when the task triggers data ingestion. This is controlled through two new options: **Use Specific Warehouse** and **Warehouse**.
+* We have released [Mendix Data Loader](/appstore/modules/snowflake/mendix-data-loader/) version 2.3.0. This version allows you to configure a specific warehouse for your task, which is used as a compute resource when the task triggers data ingestion. This is controlled through two new options: **Use Specific Warehouse** and **Warehouse**.
 
 ### June 19, 2025