|
| 1 | +--- |
| 2 | +title: "Private PDF Document Generation Service" |
| 3 | +url: /appstore/modules/private-document-generation-service/ |
| 4 | +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." |
| 5 | +#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. |
| 6 | +--- |
| 7 | + |
| 8 | +## Introduction |
| 9 | + |
| 10 | +Mendix offers a public, Mendix-hosted PDF document generation service included with the [PDF Document Generation module](/appstore/modules/document-generation/). |
| 11 | + |
| 12 | +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. |
| 13 | + |
| 14 | +### Features {#features} |
| 15 | + |
| 16 | +These are the main features of the private PDF Document Generation service: |
| 17 | + |
| 18 | +* It can run as a centralized service or as a container per app. |
| 19 | +* It can run on any container infrastructure that supports Docker as the container runtime, such as Kubernetes, AWS ECS, etc. |
| 20 | +* It has no enforced rate limits. The actual rate limit depends on the resource configuration and usage of the container. |
| 21 | +* It has configurable limits for maximum file size and maximum page rendering time. |
| 22 | + |
| 23 | +### Limitations {#limitations} |
| 24 | + |
| 25 | +These are the limitations of using the private PDF Document Generation service: |
| 26 | + |
| 27 | +* Setup, management, and monitoring of the service is your responsibility. |
| 28 | +* 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. |
| 29 | +* 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. |
| 30 | +* You are responsible for setting up a retry mechanism in the application to handle failures or timeouts of the service. |
| 31 | + |
| 32 | +### Prerequisites {#prerequisites} |
| 33 | + |
| 34 | +Before you start using the private PDF Document Generation service, make sure you meet these prerequisites: |
| 35 | + |
| 36 | +* You have a good understanding of how to run and manage Docker containers. |
| 37 | +* You are familiar with the PDF Document Generation module. For more information, refer to [PDF Document Generation](/appstore/modules/document-generation/). |
| 38 | +* Your deployment environment needs to allow bidirectional communication between Mendix apps and the Docker containers running the private PDF Document Generation service. |
| 39 | + |
| 40 | +## Installation {#installation} |
| 41 | + |
| 42 | +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. |
| 43 | + |
| 44 | +### Required Resources |
| 45 | + |
| 46 | +The required resources depend on demand. For instance, to be able to generate 5 documents in parallel, we recommend the following as a minimum: |
| 47 | + |
| 48 | +* CPU: more than 2 CPU cores |
| 49 | +* Memory: more than 4096 MB of RAM |
| 50 | + |
| 51 | +### Installing the Service |
| 52 | + |
| 53 | +The following artifact is available for installing the service: |
| 54 | + |
| 55 | +* The Docker image for the PDF Document Generation service |
| 56 | + |
| 57 | +#### Installing through Docker |
| 58 | + |
| 59 | +Follow these steps to install the service through Docker: |
| 60 | + |
| 61 | +1. Pull the Docker image using the following command: `docker pull private-cloud.registry.mendix.com/mendix/document-generation-service:<tag>`. |
| 62 | +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`. |
| 63 | + |
| 64 | +### Isolation |
| 65 | + |
| 66 | +Requests share the same container resources, which has the following implications: |
| 67 | + |
| 68 | +* Requests in the same container could affect each other in terms of performance. |
| 69 | +* Container crashes could affect all requests being processed at the time of the crash. |
| 70 | + |
| 71 | +Requests in the same container are isolated at the browser level, using an incognito browser context per request. |
| 72 | + |
| 73 | +### Scalability |
| 74 | + |
| 75 | +You can scale the service in two ways: |
| 76 | + |
| 77 | +* Using vertical scaling, with a single container setup |
| 78 | + |
| 79 | + * One container can serve multiple requests at a time, where requests are processed in parallel using an isolated browser context per request. |
| 80 | + * The browser keeps running after processing a request. |
| 81 | + * No load balancing is needed in case of a single container instance. |
| 82 | + |
| 83 | +* Using horizontal scaling, where multiple containers run in parallel |
| 84 | + |
| 85 | + * Each container can serve multiple requests at a time. |
| 86 | + |
| 87 | +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/). |
| 88 | + |
| 89 | +## Configuration {#configuration} |
| 90 | + |
| 91 | +The service has several [configuration options](#configuration-options) for adapting to your specific needs. |
| 92 | + |
| 93 | +### Setting Configuration Values {#setting-configuration-values} |
| 94 | + |
| 95 | +The approach for setting configuration values depends on the installation type. Follow the applicable instructions described in the [Available Configuration Options](#configuration-options) table. |
| 96 | + |
| 97 | +#### Configuring through Docker |
| 98 | + |
| 99 | +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>`. |
| 100 | + |
| 101 | +### Available configuration options {#configuration-options} |
| 102 | + |
| 103 | +| Environment variable | Default value | Description | |
| 104 | +|----------------------|---------------|-------------| |
| 105 | +| `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. | |
| 106 | +| `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. | |
| 107 | +| `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> | |
| 108 | + |
| 109 | +## Configuring your Mendix Apps |
| 110 | + |
| 111 | +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: |
| 112 | + |
| 113 | +* Make sure that you are using version 2.1.0 or higher of the PDF Document Generation module. |
| 114 | +* Configure the `DocumentGeneration.OverrideServiceType` constant to `Private`. |
| 115 | +* Configure the `DocumentGeneration.ServiceEndpoint` constant to point to the container address and port, such as `http://document-generation:8085`. |
| 116 | +* To generate your first document, follow the instructions in the module documentation [PDF Document Generation](/appstore/modules/document-generation/). |
| 117 | + |
| 118 | +{{% 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 %}} |
| 119 | + |
| 120 | +## Logging |
| 121 | + |
| 122 | +All application level errors are sent back to the module. Refer to [PDF Document Generation](/appstore/modules/document-generation/) for details. |
| 123 | + |
| 124 | +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. |
0 commit comments