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

Run IronPDF as a Remote Container

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 difficult to configure the environment/container to properly include all dependencies. 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: For IronPDF for Java version 2023.2.1 requires IronPdfEngine version 2023.2.1. You cannot use mistmatched 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
VB   C#

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

Or pull the specific version (recommended)

docker pull ironsoftwareofficial/ironpdfengine:2023.12.6
  1. Run the ironsoftwareofficial/ironpdfengine container.

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

docker run -d -e IRONPDF_ENGINE_LICENSE_KEY=MY_LICENSE_KEY --network=ironpdf-network --ip=172.19.0.2 --name=ironpdfengine --hostname=ironpdfengine -p 33350:33350 ironsoftwareofficial/ironpdfengine:2023.12.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. Setup 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"
  2. Set the address of IronPdfEngine inside your application (myconsoleapp) to "myironpdfengine:33350"
  3. Run docker compose
    docker compose up --detach --force-recreate --remove-orphans --timestamps

Connect to IronPdfEngine

Run your IronPDF code, your app now talks to the IronPdfEngine in Docker!

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

var config = new IronPdfConnectionConfiguration();
config.ConnectionType = IronPdfConnectionType.Docker;
IronPdf.Installation.ConnectToIronPdfHost(config);

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

Private config = New IronPdfConnectionConfiguration()
config.ConnectionType = IronPdfConnectionType.Docker
IronPdf.Installation.ConnectToIronPdfHost(config)

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

Deploy IronPdfEngine on AWS ECS

Prerequisites

Setup

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

Recommended settings:

  • AWS Fargate
  • 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.
    1. 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.
    1. Enjoy! IronPdfEngine docker is up and running in your AWS!

Please note
Horizontal scaling is not supported. Please refer to the IronPdfEngine Limitation for more information.

Deploy IronPdfEngine on Azure Container Instances

Prerequisites

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
    1. Enjoy! IronPdfEngine docker is up and running in your Azure Container Instances!

Please note
Horizontal scaling is not supported. Please refer to the IronPdfEngine Limitation for more information.

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

    Or pull the specific version (recommended)

    docker pull https://gallery.ecr.aws/v1m9w8y1/ironpdfengine:2023.12.6
  3. Run ironpdfengine container. This command will create a container and run in the background with port 33350
    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

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, on the left sidebar, go to Kubernetes resources -> Run command. Run the following command:
    kubectl get services
Kubernetes service - run command

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")
VB   C#

AWS Marketplace

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.

    Accept EULA

  3. Continue to Confiuguration.

    Subscribe complete

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

    Launch this software

    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
  5. 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