1. IronPDF
2. Get Started
3. Host and Use IronPdfEngine in Docker

Run IronPDF as a Remote Container

Chaknith Bin

Updated:August 3, 2025

The IronPdfEngine is a standalone service which can handle the creating, writing, editing, and reading of PDFs. IronPDF Docker is ready to run docker services with compatible versions of IronPDF (v2023.2.x and above). This will help developers eradicate deployment issues that they may be experiencing with IronPDF.

Why running IronPDF as its own container is a good idea

IronPDF requires both Chrome and Pdfium binaries in order to operate which are huge in file size (hundreds of MBs). It also requires several dependencies to be installed on the machine.

By using this method, your client will only take up a fraction of the size (in MB).

Avoid Deployment Issues

It can be challenging to configure the environment/container to include all dependencies properly. Using the IronPDF Docker container means that IronPDF comes pre-installed and guaranteed to work, avoiding all deployment and dependency headaches.

Versions

The IronPDF Docker tag is based on the version of IronPdfEngine itself. It is not the same version as the IronPDF product.

Each IronPDF version will have its own associated IronPdfEngine version. The version number must match the IronPDF Docker version.

For example, IronPDF for Java version 2023.2.1 requires IronPdfEngine version 2023.2.1. You cannot use mismatched IronPdfEngine and IronPDF versions.

How to use IronPDF Docker

Install IronPDF

Add the IronPdf.Slim Nuget package to your project.

https://www.nuget.org/packages/IronPdf.Slim/

Note: IronPdf, IronPdf.Linux and IronPdf.MacOs packages all contain IronPdf.Slim.

To reduce your application size, we recommend installing just IronPdf.Slim. Package IronPdf.Native.Chrome.xxx is no longer used, so you can remove it from your project.

Determine Required Container Version

By default, the IronPDF for Docker version will match the current version of IronPDF on NuGet. You may use the code below to check the version manually:

:path=/static-assets/pdf/content-code-examples/how-to/ironpdfengine-docker-version.cs

string ironPdfEngineVersion = IronPdf.Installation.IronPdfEngineVersion;

Dim ironPdfEngineVersion As String = IronPdf.Installation.IronPdfEngineVersion

Setup IronPDF for Docker Container

Without Docker Compose

Run the docker container using the version from the previous step.

• Docker must be installed.

Setup

1. Go to https://hub.docker.com/r/ironsoftwareofficial/ironpdfengine
2. Pull the latest ironsoftwareofficial/ironpdfengine image

docker pull ironsoftwareofficial/ironpdfengine

docker pull ironsoftwareofficial/ironpdfengine

Or pull the specific version (recommended)

docker pull ironsoftwareofficial/ironpdfengine:2025.3.6

docker pull ironsoftwareofficial/ironpdfengine:2025.3.6

3. Run the ironsoftwareofficial/ironpdfengine container.

This command will create a container and run it in the background with port 33350

docker run -d -p 33350:33350 -e IRONPDF_ENGINE_LICENSE_KEY=MY_LICENSE_KEY ironsoftwareofficial/ironpdfengine:2025.3.6

docker run -d -p 33350:33350 -e IRONPDF_ENGINE_LICENSE_KEY=MY_LICENSE_KEY ironsoftwareofficial/ironpdfengine:2025.3.6

With Docker Compose

The key is to set up a Docker network that allows IronPdfEngine and your application to see each other. Set 'depends_on' to ensure that IronPdfEngine is up before your application starts.

Setup

1. Start by creating a docker-compose.yml file. Set up your Docker Compose file using the following template:

version: '3.6'
services:
  myironpdfengine:
    container_name: ironpdfengine
    image: ironsoftwareofficial/ironpdfengine:latest
    ports:
      - '33350:33350'
    networks:
      - ironpdf-network
  myconsoleapp:
    container_name: myconsoleapp
    build:
      # enter YOUR project directory path here
      context: ./MyConsoleApp/
      # enter YOUR dockerfile name here, relative to project directory
      dockerfile: Dockerfile
    networks:
      - ironpdf-network
    depends_on:
      myironpdfengine:
        condition: service_started
networks:
  ironpdf-network: 
    driver: 'bridge'

1. Set the address of IronPdfEngine inside your application (myconsoleapp) to "myironpdfengine:33350"
2. Run docker compose

docker compose up --detach --force-recreate --remove-orphans --timestamps

docker compose up --detach --force-recreate --remove-orphans --timestamps

Connect to IronPdfEngine

Run your IronPDF code; your app now communicates with the IronPdfEngine in Docker!

:path=/static-assets/pdf/content-code-examples/how-to/ironpdfengine-docker-use.cs

using IronPdf;
using IronPdf.GrpcLayer;

// Configure for Docker container
var config = IronPdfConnectionConfiguration.Docker;
config.Host = "localhost";
IronPdf.Installation.ConnectToIronPdfHost(config);

// Use IronPDF
ChromePdfRenderer renderer = new ChromePdfRenderer();
PdfDocument pdf = renderer.RenderHtmlAsPdf("<h1>Hello IronPDF Docker!<h1>");
pdf.SaveAs("ironpdf.pdf");

Imports IronPdf
Imports IronPdf.GrpcLayer

' Configure for Docker container
Private config = IronPdfConnectionConfiguration.Docker
config.Host = "localhost"
IronPdf.Installation.ConnectToIronPdfHost(config)

' Use IronPDF
Dim renderer As New ChromePdfRenderer()
Dim pdf As PdfDocument = renderer.RenderHtmlAsPdf("<h1>Hello IronPDF Docker!<h1>")
pdf.SaveAs("ironpdf.pdf")

Connection Type

There are several IronPdfConnectionType that you can assign depending on the connection type you wish to make.

Here's a list of available properties:

LocalExcutable: To connect to an IronPdfEngine "server" running an executable on your local machine, we use this option. A quick example would be a WinForm invoicing application that generates PDFs locally without relying on cloud services.

Docker: This option should be used when trying to connect to a Docker container either locally or in the cloud.

RemoteServer: This option is used for IronPdfEngine in the cloud. This connects to a cloud-hosted (e.g., Docker) IronPdfEngine instance through the HTTP or HTTPS protocol. Note that, since this is connecting to a remote server, the full URL is required (including the HTTP or HTTPS protocol).

Custom: For full control and customization over the connection, you can use this option. This option uses your custom-defined Grpc.Core.ChannelBase instead of the other defined options from above. Developers can create a new channel by either creating a new Grpc.Core.Channel object or using Grpc.Net.Client.GrpcChannel.ForAddress(System.String) to custom and complete control over the gRPC channel.

.NET Framework with NetFrameworkChannel

For .NET Framework, we require a different setup because gRPC works differently in .NET Framework projects. For this method to work, please ensure the Grpc.Core NuGet package is installed. We'll be using a custom gRPC channel derived from Grpc.Core.ChannelBase for this specific setup.

Let's examine this example, where we'll implement the connection channel to create and save a PDF using IronPDFEngine.

:path=/static-assets/pdf/content-code-examples/how-to/ironpdfengine-docker-use-grpc.cs

using IronPdf;
using IronPdf.GrpcLayer;
using Grpc.Core;
// This code demonstrates how to use IronPdf with gRPC in a .NET Framework application.

// 1. Configure connection to use local IronPdfEngine executable
var config = IronPdf.GrpcLayer.IronPdfConnectionConfiguration.Executable;
        
// 2. Connect to the IronPDF host with the executable configuration
IronPdf.Installation.ConnectToIronPdfHost(config);
        
// 3. Create a PDF renderer instance
ChromePdfRenderer renderer = new ChromePdfRenderer();
        
// 4. Render HTML string as PDF document
PdfDocument pdf = renderer.RenderHtmlAsPdf("Hello world");
        
// 5. Save the PDF to disk
pdf.SaveAs("output.pdf");
        
// 6. Clean up , this is needed to work
pdf.Dispose();

Imports IronPdf
Imports IronPdf.GrpcLayer
Imports Grpc.Core
' This code demonstrates how to use IronPdf with gRPC in a .NET Framework application.

' 1. Configure connection to use local IronPdfEngine executable
Private config = IronPdf.GrpcLayer.IronPdfConnectionConfiguration.Executable

' 2. Connect to the IronPDF host with the executable configuration
IronPdf.Installation.ConnectToIronPdfHost(config)

' 3. Create a PDF renderer instance
Dim renderer As New ChromePdfRenderer()

' 4. Render HTML string as PDF document
Dim pdf As PdfDocument = renderer.RenderHtmlAsPdf("Hello world")

' 5. Save the PDF to disk
pdf.SaveAs("output.pdf")

' 6. Clean up , this is needed to work
pdf.Dispose()

Alternative method with WithCustomChannel

An alternative method would be to utilize the WithCustomChannel method provided by the IronPdf.GrpcLayer.

The WithCustomChannel takes in two parameters, the customChannel, which is your custom gRPC channel, and metadata. The metadata parameter is optional and is set to null by default.

:path=/static-assets/pdf/content-code-examples/how-to/ironpdfengine-docker-use-grpc-alt.cs

using Grpc.Core;
using IronPdf;
using IronPdf.GrpcLayer;


// 1. Create custom gRPC channel (.NET Framework style)
var channel = new Channel("123.456.7.8:80",  ChannelCredentials.SecureSsl);

// 2. (Optional) Add metadata headers if needed
var metadata = new Metadata
    {
        { "Authorization", "Bearer your_token_here" }
    };

// 3. Configure IronPDF with custom channel
var config = IronPdfConnectionConfiguration.WithCustomChannel(channel, metadata);
IronPdf.Installation.ConnectToIronPdfHost(config);

// 4. Generate PDF
var renderer = new ChromePdfRenderer();
PdfDocument pdf = renderer.RenderHtmlAsPdf("Hello world");

// 5. Save the PDF to disk
pdf.SaveAs("output.pdf");

// 6. Clean up , this is needed to work
pdf.Dispose();

Imports Grpc.Core
Imports IronPdf
Imports IronPdf.GrpcLayer


' 1. Create custom gRPC channel (.NET Framework style)
Private channel = New Channel("123.456.7.8:80", ChannelCredentials.SecureSsl)

' 2. (Optional) Add metadata headers if needed
Private metadata = New Metadata From {
	{ "Authorization", "Bearer your_token_here" }
}

' 3. Configure IronPDF with custom channel
Private config = IronPdfConnectionConfiguration.WithCustomChannel(channel, metadata)
IronPdf.Installation.ConnectToIronPdfHost(config)

' 4. Generate PDF
Dim renderer = New ChromePdfRenderer()
Dim pdf As PdfDocument = renderer.RenderHtmlAsPdf("Hello world")

' 5. Save the PDF to disk
pdf.SaveAs("output.pdf")

' 6. Clean up , this is needed to work
pdf.Dispose()

Deploy IronPdfEngine on AWS ECS

Prerequisites

• Pull the IronPdfEngine Docker image. This is in the Setup IronPDF for Docker Container above.
• An AWS account with access to ECS.

Setup

1. Create an ECS Cluster. Follow this guide to create a cluster for the Fargate and External launch types using the console.
2. Create a task definition. Follow this guide for creating a task definition using the console.

Recommended settings:

• AWS Fargate
• A minimum 1 vCPU with 2 GB of RAM is recommended. Depending on your workload, if you are working with PDFs containing more than 10 pages or experiencing heavy load requests, please select a higher tier.
• Network mode: awsvpc
• Port mappings:

  {
    "containerPort": 33350,
    "hostPort": 33350,
    "protocol": "tcp",
    "appProtocol": "grpc"
  }

• Image URI: point to any IronPdfEngine from us. For example, "ironsoftwareofficial/ironpdfengine:2024.1.20" (from DockerHub)
• AWS Permission & Networking are on your own
• Enable Amazon CloudWatch is recommended. (Enable logging)
• Container startup order is necessary if you want to deploy your application container in the same task definition.

3. Run a task definition. You could run a task definition as a Task or Service. Follow this guide on creating a service using the console.

Recommended settings:

• Launch type: AWS Fargate
• Public IP: Turned on for test and Turned off for production. Security and AWS Networking are on your own.

4. Enjoy! IronPdfEngine docker is up and running in your AWS!

Deploy IronPdfEngine on Azure Container Instances

Prerequisites

• Pull the IronPdfEngine Docker image. This is in the Setup IronPDF for Docker Container above.
• Azure Account

Setup

1. Create an Azure Container. Follow this quickstart guide on deploying a container instance in Azure using the Azure portal.

Recommended settings:

• Image source: Other registry
• Image: ironsoftwareofficial/ironpdfengine:2024.1.20 (from Docker Hub)
• OS type: Linux
• Size: Minimum of 1 vCPU and 2 GiB of memory, or higher
• Port: TCP Port 33350

2. Enjoy! IronPdfEngine docker is up and running in your Azure Container Instances!

Getting IronPdfEngine in AWS ECR Public Gallery

Prerequisite

• Docker must be installed.

Setup

1. Go to https://gallery.ecr.aws/v1m9w8y1/ironpdfengine
2. Pull the v1m9w8y1/ironpdfengine image

docker pull https://gallery.ecr.aws/v1m9w8y1/ironpdfengine

docker pull https://gallery.ecr.aws/v1m9w8y1/ironpdfengine

Or pull the specific version (recommended)

docker pull https://gallery.ecr.aws/v1m9w8y1/ironpdfengine:2023.12.6

docker pull https://gallery.ecr.aws/v1m9w8y1/ironpdfengine:2023.12.6

3. Run ironpdfengine container.

This command will create a container and run it in the background with port 33350

docker run -d -p 33350:33350 ironsoftwareofficial/ironpdfengine

docker run -d -p 33350:33350 ironsoftwareofficial/ironpdfengine

Learn how to configure the IronPdf client to utilize IronPdfEngine by navigating to the section "Update the Code to Use IronPdfEngine."

Get IronPdfEngine from the Marketplace

To help you get started quickly, we have set up IronPdfEngine on both the Azure and AWS Marketplaces.

Azure Marketplace

Setup

1. Go to IronPDF Docker Container on Azure Marketplace. Click on the "Get It Now" and "Continue."
2. Complete the "Basics", "Cluster Details", and "Application Details" to create the Kubernetes service.
3. Once the deployment has completed, navigate to the left sidebar and select Kubernetes resources> Run command. Run the following command:

kubectl get services

kubectl get services

With the information of EXTERNAL-IP and PORT(S), you can configure the IronPDFEngine connection accordingly.

:path=/static-assets/pdf/content-code-examples/how-to/pull-run-ironpdfengine-azure-marketplace.cs

using IronPdf;
using IronPdf.GrpcLayer;

IronPdf.License.LicenseKey = "IRONPDF-MYLICENSE-KEY-1EF01";

IronPdfConnectionConfiguration configuration = new IronPdfConnectionConfiguration();
configuration.ConnectionType = IronPdfConnectionType.RemoteServer;
configuration.Host = "http://48.216.143.233";
configuration.Port = 80;
IronPdf.Installation.ConnectToIronPdfHost(configuration);

ChromePdfRenderer renderer = new ChromePdfRenderer();
PdfDocument pdf = renderer.RenderHtmlAsPdf("<h1>testing</h1>");
pdf.SaveAs("output.pdf");

Imports IronPdf
Imports IronPdf.GrpcLayer

IronPdf.License.LicenseKey = "IRONPDF-MYLICENSE-KEY-1EF01"

Dim configuration As New IronPdfConnectionConfiguration()
configuration.ConnectionType = IronPdfConnectionType.RemoteServer
configuration.Host = "http://48.216.143.233"
configuration.Port = 80
IronPdf.Installation.ConnectToIronPdfHost(configuration)

Dim renderer As New ChromePdfRenderer()
Dim pdf As PdfDocument = renderer.RenderHtmlAsPdf("<h1>testing</h1>")
pdf.SaveAs("output.pdf")

AWS Marketplace

Prerequisites

• Docker must be installed.
• AWS CLI must be installed and logged in.

Setup

1. Go to IronPdfEngine on AWS marketplace. Click on the 'Continue to Subscribe.'

2. Accept the Terms.

4. Continue to Configuration.

5. Pull the ironpdfengine image. This step will show you a command to pull the ironpdfengine image.

For Example:

aws ecr get-login-password \
    --region us-east-1 | docker login \
    --username AWS \
    --password-stdin 000000000000.dkr.ecr.us-east-1.amazonaws.com
CONTAINER_IMAGES="000000000000.dkr.ecr.us-east-1.amazonaws.com/iron-software/ironpdfengine:2024.1.15"    
for i in $(echo $CONTAINER_IMAGES | sed "s/,/ /g"); do docker pull $i; done

aws ecr get-login-password \
    --region us-east-1 | docker login \
    --username AWS \
    --password-stdin 000000000000.dkr.ecr.us-east-1.amazonaws.com
CONTAINER_IMAGES="000000000000.dkr.ecr.us-east-1.amazonaws.com/iron-software/ironpdfengine:2024.1.15"    
for i in $(echo $CONTAINER_IMAGES | sed "s/,/ /g"); do docker pull $i; done

6. Run the ironpdfengine container. This command will create a container and run it in the background with port 33350.

docker run -d -p 33350:33350 000000000000.dkr.ecr.us-east-1.amazonaws.com/iron-software/ironpdfengine:2024.1.15

docker run -d -p 33350:33350 000000000000.dkr.ecr.us-east-1.amazonaws.com/iron-software/ironpdfengine:2024.1.15

Health Check For IronPdfEngine

Checking on the health of your Docker Container is crucial for ensuring reliability and availability in a production environment. The ability to check for the IronPdfEngine Docker container allows developers to restart the service if it fails, as well as scale resources if the demand increases, along with monitoring a continuous application.

To check on the health of your IronPdfEngine, we can send a gRPC request to the same IronPdfEngine port (by default, it would be 33350) to verify if we get a response.

Health Check with gRPC

IronPdfEngine adheres to the standard gRPC health check pattern, utilizing the following protocol structure.

message HealthCheckRequest {
 string service = 1; // Name of the service to check (e.g., "IronPdfEngine")
}

Since we're checking for IronPdfEngine, we replace the service name with IronPdfEngine.

Here's an example using JavaScript with Postman to send a gRPC request to the local IronPdfEngine service with the default number of 33350.

As you can see from the response, the status response is SERVING, indicating the service is up and running. If the container is not healthy, the status response would be NOT_SERVING.

Health Check with Kubernetes Setup

For Kubernetes setups, we can use the following to check whether the service is healthy or not.

 livenessProbe:
          exec:
            command:
            - /bin/grpc_health_probe
            - -addr=:33350
            - -rpc-timeout=5s

 livenessProbe:
          exec:
            command:
            - /bin/grpc_health_probe
            - -addr=:33350
            - -rpc-timeout=5s

Chaknith Bin

  Chat with engineering team now

Software Engineer

Chaknith works on IronXL and IronBarcode. He has deep expertise in C# and .NET, helping improve the software and support customers. His insights from user interactions contribute to better products, documentation, and overall experience.

Ready to Get Started?

Free NuGet Download Total downloads: 15,030,178

View Licenses