Using EvoPdf Next for .NET in AWS Elastic Beanstalk on Linux

EvoPdf Next for .NET is a library that can be integrated into applications running in AWS Elastic Beanstalk on Linux to create and process PDF documents.

You can create PDF documents, convert HTML, Word, Excel, RTF and Markdown documents to PDF, extract text and images from existing PDF documents, perform text search operations on PDF documents and convert PDF pages to images.

EvoPdf Next for .NET runs in 64-bit applications deployed to the .NET platform for Linux of AWS Elastic Beanstalk, based on Amazon Linux 2023, on x86_64 instances and on arm64 instances with AWS Graviton processors.

The HTML to PDF Converter component requires a few system packages and execute permission on its runtime files. Both are set up by a configuration file included in the application, which Elastic Beanstalk applies at every deployment and on every new instance. The other components don't require any additional setup.

The library targets .NET Standard 2.0, making it usable in any .NET Core application that supports this standard.

Create a new .NET project in Visual Studio and use the NuGet Package Manager to add a reference to the EvoPdf.Next.Linux NuGet metapackage which will install all the library components. For arm64 instances with AWS Graviton processors reference the EvoPdf.Next.Linux.Arm64 metapackage.

To install only specific components of the EvoPdf Next library you can add references to the corresponding NuGet packages. You can find more details about the available packages in the Getting Started on Linux documentation section.

After installing the package, add the using EvoPdf.Next; directive at the top of your source files to access the EvoPdf Next API.

Add the two configuration files below to the root folder of your project. Elastic Beanstalk reads them from the root of the application bundle.

Install the Required Packages

Create the .ebextensions/evopdf.config file with the content below. The packages section installs the libraries required by the HTML to PDF Converter and the DejaVu font families, which render the text of pages that do not use web fonts. The files section sets DejaVu Sans as the sans-serif font. The container commands give execute permission to the runtime files, which an application bundle created on Windows does not keep. Indent the file with spaces, not tabs.

packages:
  yum:
    nss: []
    at-spi2-atk: []
    cairo: []
    pango: []
    dejavu-sans-fonts: []
    dejavu-serif-fonts: []
    dejavu-sans-mono-fonts: []
files:
  "/etc/fonts/local.conf":
    mode: "000644"
    owner: root
    group: root
    content: |
      <fontconfig>
        <alias>
          <family>sans-serif</family>
          <prefer><family>DejaVu Sans</family></prefer>
        </alias>
      </fontconfig>
container_commands:
  01_evopdf_loadhtml:
    command: "chmod +x evopdf_runtimes/linux-x64/native/evopdf_loadhtml"
  02_evopdf_pdfprocessor:
    command: "chmod +x evopdf_runtimes/linux-x64/native/evopdf_pdfprocessor"

On arm64 instances, where the application references the EvoPdf.Next.Linux.Arm64 package, replace linux-x64 with linux-arm64 in the two paths.

Raise the Proxy Limits

Elastic Beanstalk runs nginx in front of the application. With its default settings a request ends after 60 seconds and request bodies larger than 1 MB are rejected. For applications that run long conversions or receive uploaded documents, create the .platform/nginx/conf.d/evopdf.conf file:

proxy_read_timeout 300;
client_max_body_size 50M;

Include the Files in the Publish Output

Add the two folders to the project file, so that every publish copies them next to the application:

<ItemGroup>
  <None Include=".ebextensions\**" CopyToPublishDirectory="PreserveNewest" />
  <None Include=".platform\**" CopyToPublishDirectory="PreserveNewest" />
</ItemGroup>

Publish the application for Linux:

dotnet publish -c Release -r linux-x64 --self-contained false -o publish

The application bundle is a zip archive with the content of the publish folder at its root, including the .ebextensions and .platform folders. In File Explorer, open the publish folder, select all its content and choose Send to > Compressed (zipped) folder. Elastic Beanstalk finds the application by its runtimeconfig.json file, so a Procfile is not needed. Elastic Beanstalk does not extract archives that store the paths with backslashes, such as the archives some Windows PowerShell commands create.

In the Elastic Beanstalk console, choose Create application and create a Web server environment:

• Platform: the .NET platform for Linux, with the platform branch running on 64bit Amazon Linux 2023 for the .NET version of your application, for example .NET 10 running on 64bit Amazon Linux 2023. An application does not start on the platform branch of another .NET version.

• Application code: Local file, then choose the zip archive.

• Service access: the service role and the EC2 instance profile of Elastic Beanstalk. The instance profile, usually named aws-elasticbeanstalk-ec2-role, must exist before the first environment is created; if the list is empty, create it in the IAM console with the Elastic Beanstalk - Compute use case.

• Instance types: HTML to PDF conversion can be resource-intensive, depending on the complexity of the content. The t3.medium instance type (2 vCPUs, 4 GB RAM) is the minimum we recommend, in place of the t3.micro type the console selects. For production workloads with complex or large documents choose an instance type with more memory.

In a load-balanced environment each new instance runs the configuration file before it receives requests, so no instance needs manual setup.

When the health of the environment is Ok, open the environment URL to run your application. To deploy a new version, choose Upload and deploy on the environment page and select the new zip archive.

You can follow the same steps to publish the EvoPdf Next ASP.NET demo application, from the EvoPdf_Next_AspNetDemo_Linux_net10.0.csproj project for the .NET 10 platform or the EvoPdf_Next_AspNetDemo_Linux_net8.0.csproj project for the .NET 8 platform, after you copy the two configuration folders to its publish folder.

On the environment page choose Logs > Request logs. The /var/log/eb-engine.log file shows the result of the configuration file, including the installation of the packages. The /var/log/web.stdout.log file shows the output of the application.

Reference

Other Resources