Publish HiQPdf Next ASP.NET Demo to Docker on Linux

This guide explains how to build and run a Docker container for a published ASP.NET Core application using HiQPdf Next on Linux.

Compatibility with Linux Docker Images

HiQPdf Next can run in various Linux Docker containers that have the ASP.NET Core runtime preinstalled, such as Linux Debian 12 with ASP.NET Core Runtime 8.0 using the mcr.microsoft.com/dotnet/aspnet:8.0 image reference and Linux Ubuntu 24.04 with ASP.NET Core Runtime 10.0 using the mcr.microsoft.com/dotnet/aspnet:10.0 image reference. Both x64 (linux-x64) and ARM64 (linux-arm64) architectures are supported. The .NET base images are multi-architecture, so the same image reference automatically selects the matching architecture for the host.

Publish the Demo Application to a Folder

Download the HiQPdf Next ZIP package from the website downloads page and extract it to a folder on your machine. In the AspNetDemo folder of the extracted package you can find the demo application. Its sources are shared by all the platforms and one project file references the HiQPdf Next library NuGet package for Linux for each supported .NET version. You can open the HiQPdf_Next_AspNetDemo_Linux_net10.0.csproj file in Visual Studio and publish it to a folder or publish it from the command line.

To publish from the command line, run the following command in the application folder containing the HiQPdf_Next_AspNetDemo_Linux_net10.0.csproj project file:

bash
# .NET 10, for the Dockerfile with the ASP.NET Core Runtime 10.0 base image
dotnet publish -c Release -r linux-x64 -o publish/linux-x64-net10.0 HiQPdf_Next_AspNetDemo_Linux_net10.0.csproj

# .NET 8, for the Dockerfile with the ASP.NET Core Runtime 8.0 base image
dotnet publish -c Release -r linux-x64 -o publish/linux-x64-net8.0 HiQPdf_Next_AspNetDemo_Linux_net8.0.csproj

You can find more details about building and publishing the HiQPdf Next demo applications in the Build and Publish Demo Applications guide in the documentation.

The publish/linux-x64-net10.0 folder should include the main DLL (for example, HiQPdf_Next_AspNetDemo_Linux_net10.0.dll) and the hiqpdf_runtimes directory at the root level.

Place this publish folder in the build context folder of the Linux host file system, which will also contain the Dockerfile.

Create the Dockerfile for Linux with Preinstalled ASP.NET Core Runtime

HiQPdf Next can run in Linux containers with the ASP.NET Core runtime.

Below you can find the Dockerfile configurations for the default Linux Debian 12 with ASP.NET Core Runtime 8.0 and Linux Ubuntu 24.04 with ASP.NET Core Runtime 10.0 images. Copy the contents into a file named Dockerfile and place it in the build context folder together with the publish folder.

You can also customize the Dockerfile to use other Linux distributions that have the ASP.NET Core runtime preinstalled. As an example, a Dockerfile is provided below for Linux Ubuntu 22.04 (jammy) with ASP.NET Core Runtime 8.0 using the mcr.microsoft.com/dotnet/aspnet:8.0-jammy image.

The Dockerfile installs the required Linux dependencies, copies the published application into the image, grants execute permissions to the HiQPdf Next runtime and configures the container to run the demo application on port 28101.

Dockerfile for Linux Debian 12 with Preinstalled ASP.NET Core Runtime 8.0

 
FROM mcr.microsoft.com/dotnet/aspnet:8.0

# Install HiQPdf dependencies
RUN apt-get update && \
    apt-get install -y \
        libnss3 \
        libatk-bridge2.0-0 \
        libcairo2 \
        libpango-1.0-0 && \
    rm -rf /var/lib/apt/lists/*

# Set the working directory
WORKDIR /app

# Copy the published ASP.NET Core app files from the publish folder into the image
COPY publish/linux-x64-net8.0/ .

# Ensure execute permissions for HiQPdf HTML to PDF runtime
RUN chmod +x /app/hiqpdf_runtimes/linux-x64/native/hiqpdf_loadhtml

# Ensure execute permissions for HiQPdf PDF Processor runtime
RUN chmod +x /app/hiqpdf_runtimes/linux-x64/native/hiqpdf_pdfprocessor

# Expose the port used by the app
EXPOSE 28101

# Set the ASP.NET Core application to listen on port 28101
ENV ASPNETCORE_URLS=http://+:28101

# Start the application
ENTRYPOINT ["dotnet", "HiQPdf_Next_AspNetDemo_Linux_net8.0.dll"]

Dockerfile for Linux Ubuntu 24.04 with Preinstalled ASP.NET Core Runtime 10.0

 
FROM mcr.microsoft.com/dotnet/aspnet:10.0

# Install HiQPdf dependencies
RUN apt-get update && \
    apt-get install -y \
        libnss3 \
        libatk-bridge2.0-0 \
        libcairo2 \
        libpango-1.0-0 && \
    rm -rf /var/lib/apt/lists/*

# Set the working directory
WORKDIR /app

# Copy the published ASP.NET Core app files from the publish folder into the image
COPY publish/linux-x64-net10.0/ .

# Ensure execute permissions for HiQPdf HTML to PDF runtime
RUN chmod +x /app/hiqpdf_runtimes/linux-x64/native/hiqpdf_loadhtml

# Ensure execute permissions for HiQPdf PDF Processor runtime
RUN chmod +x /app/hiqpdf_runtimes/linux-x64/native/hiqpdf_pdfprocessor

# Expose the port used by the app
EXPOSE 28101

# Set the ASP.NET Core application to listen on port 28101
ENV ASPNETCORE_URLS=http://+:28101

# Start the application
ENTRYPOINT ["dotnet", "HiQPdf_Next_AspNetDemo_Linux_net10.0.dll"]

Dockerfile for Linux Ubuntu 22.04 with Preinstalled ASP.NET Core Runtime 8.0

 
FROM mcr.microsoft.com/dotnet/aspnet:8.0-jammy

# Install HiQPdf dependencies
RUN apt-get update && \
    apt-get install -y \
        libnss3 \
        libatk-bridge2.0-0 \
        libcairo2 \
        libpango-1.0-0 && \
    rm -rf /var/lib/apt/lists/*

# Set the working directory
WORKDIR /app

# Copy the published ASP.NET Core app files from the publish folder into the image
COPY publish/linux-x64-net8.0/ .

# Ensure execute permissions for HiQPdf HTML to PDF runtime
RUN chmod +x /app/hiqpdf_runtimes/linux-x64/native/hiqpdf_loadhtml

# Ensure execute permissions for HiQPdf PDF Processor runtime
RUN chmod +x /app/hiqpdf_runtimes/linux-x64/native/hiqpdf_pdfprocessor

# Expose the port used by the app
EXPOSE 28101

# Set the ASP.NET Core application to listen on port 28101
ENV ASPNETCORE_URLS=http://+:28101

# Start the application
ENTRYPOINT ["dotnet", "HiQPdf_Next_AspNetDemo_Linux_net8.0.dll"]

Build and Run the Container

Once the Dockerfile is created as described in the previous sections, you can build and run the container using the following commands.

Use the following command to build the Docker image:

 
docker build -t hiqpdf-next-demo-image-linux .

Then run the container:

 
docker run -d -p 28101:28101 --name hiqpdf-next-demo-app-linux hiqpdf-next-demo-image-linux

Open your browser and access the application at:

 
http://localhost:28101

You can also publish the Docker image to Azure Container Registry (ACR) and run the application directly from there, enabling easier deployment and integration within Azure-based environments.

Building for Linux ARM64

To build a container for Linux ARM64, make three changes to the x64 build: publish with the linux-arm64 runtime identifier, use the linux-arm64 native runtime paths in the Dockerfile and reference the ARM64 application DLL. Keep the same base image reference as for x64.

Publish the ARM64 project from the command line:

bash
# .NET 10, for the Dockerfile with the ASP.NET Core Runtime 10.0 base image
dotnet publish -c Release -r linux-arm64 -o publish/linux-arm64-net10.0 HiQPdf_Next_AspNetDemo_Linux.Arm64_net10.0.csproj

# .NET 8, for the Dockerfile with the ASP.NET Core Runtime 8.0 base image
dotnet publish -c Release -r linux-arm64 -o publish/linux-arm64-net8.0 HiQPdf_Next_AspNetDemo_Linux.Arm64_net8.0.csproj

The publish folder will contain the ARM64 native runtime under hiqpdf_runtimes/linux-arm64 instead of linux-x64.

Below are the Dockerfile configurations for the default Linux Debian 12 with ASP.NET Core Runtime 8.0, Linux Ubuntu 24.04 with ASP.NET Core Runtime 10.0 and Linux Ubuntu 22.04 (jammy) with ASP.NET Core Runtime 8.0 images. They are identical to the x64 Dockerfiles except for the native runtime paths in the chmod commands and the application DLL name.

Dockerfile for Linux Debian 12 with Preinstalled ASP.NET Core Runtime 8.0

 
FROM mcr.microsoft.com/dotnet/aspnet:8.0

# Install HiQPdf dependencies
RUN apt-get update && \
    apt-get install -y \
        libnss3 \
        libatk-bridge2.0-0 \
        libcairo2 \
        libpango-1.0-0 && \
    rm -rf /var/lib/apt/lists/*

# Set the working directory
WORKDIR /app

# Copy the published ASP.NET Core app files from the publish folder into the image
COPY publish/linux-arm64-net8.0/ .

# Ensure execute permissions for HiQPdf HTML to PDF runtime
RUN chmod +x /app/hiqpdf_runtimes/linux-arm64/native/hiqpdf_loadhtml

# Ensure execute permissions for HiQPdf PDF Processor runtime
RUN chmod +x /app/hiqpdf_runtimes/linux-arm64/native/hiqpdf_pdfprocessor

# Expose the port used by the app
EXPOSE 28101

# Set the ASP.NET Core application to listen on port 28101
ENV ASPNETCORE_URLS=http://+:28101

# Start the application
ENTRYPOINT ["dotnet", "HiQPdf_Next_AspNetDemo_Linux.Arm64_net8.0.dll"]

Dockerfile for Linux Ubuntu 24.04 with Preinstalled ASP.NET Core Runtime 10.0

 
FROM mcr.microsoft.com/dotnet/aspnet:10.0

# Install HiQPdf dependencies
RUN apt-get update && \
    apt-get install -y \
        libnss3 \
        libatk-bridge2.0-0 \
        libcairo2 \
        libpango-1.0-0 && \
    rm -rf /var/lib/apt/lists/*

# Set the working directory
WORKDIR /app

# Copy the published ASP.NET Core app files from the publish folder into the image
COPY publish/linux-arm64-net10.0/ .

# Ensure execute permissions for HiQPdf HTML to PDF runtime
RUN chmod +x /app/hiqpdf_runtimes/linux-arm64/native/hiqpdf_loadhtml

# Ensure execute permissions for HiQPdf PDF Processor runtime
RUN chmod +x /app/hiqpdf_runtimes/linux-arm64/native/hiqpdf_pdfprocessor

# Expose the port used by the app
EXPOSE 28101

# Set the ASP.NET Core application to listen on port 28101
ENV ASPNETCORE_URLS=http://+:28101

# Start the application
ENTRYPOINT ["dotnet", "HiQPdf_Next_AspNetDemo_Linux.Arm64_net10.0.dll"]

Dockerfile for Linux Ubuntu 22.04 with Preinstalled ASP.NET Core Runtime 8.0

 
FROM mcr.microsoft.com/dotnet/aspnet:8.0-jammy

# Install HiQPdf dependencies
RUN apt-get update && \
    apt-get install -y \
        libnss3 \
        libatk-bridge2.0-0 \
        libcairo2 \
        libpango-1.0-0 && \
    rm -rf /var/lib/apt/lists/*

# Set the working directory
WORKDIR /app

# Copy the published ASP.NET Core app files from the publish folder into the image
COPY publish/linux-arm64-net8.0/ .

# Ensure execute permissions for HiQPdf HTML to PDF runtime
RUN chmod +x /app/hiqpdf_runtimes/linux-arm64/native/hiqpdf_loadhtml

# Ensure execute permissions for HiQPdf PDF Processor runtime
RUN chmod +x /app/hiqpdf_runtimes/linux-arm64/native/hiqpdf_pdfprocessor

# Expose the port used by the app
EXPOSE 28101

# Set the ASP.NET Core application to listen on port 28101
ENV ASPNETCORE_URLS=http://+:28101

# Start the application
ENTRYPOINT ["dotnet", "HiQPdf_Next_AspNetDemo_Linux.Arm64_net8.0.dll"]

Build and Run the ARM64 Container

Build the image on an ARM64 host:

 
docker build -t hiqpdf-next-demo-image-linux-arm64 .

Or build for ARM64 from an x64 host using emulation:

 
docker build --platform linux/arm64 -t hiqpdf-next-demo-image-linux-arm64 .

Then run the container:

 
docker run -d --platform linux/arm64 -p 28101:28101 --name hiqpdf-next-demo-app-linux-arm64 hiqpdf-next-demo-image-linux-arm64

See Also