Using Aspose.HTML for Java in Docker – Run HTML Conversion & Processing Anywhere

Overview

This guide shows how to run Aspose.HTML for Java inside a Docker container using a Dockerfile.

Docker packages your application together with its runtime and dependencies into an isolated image. As a result, you can run HTML conversion and processing consistently on any machine where Docker is available (local workstation, CI, or production servers).

Requirements

For predictable HTML-to-PDF/image rendering you typically need fonts inside the container.

Required package:

• ttf-mscorefonts-installer — Microsoft TrueType Core Fonts (includes common fonts such as Arial).

Note: On Alpine images the ttf-mscorefonts-installer package may not be available in all repositories. If you hit this limitation, use the manual installation approach shown below, or consider a Debian/Ubuntu-based base image where font packages are usually more accessible.

Example on GitHub

A working Docker example is available in the Aspose GitHub repository:

Docker Example on GitHub

Step-by-Step Instructions

1) Install Docker

Make sure Docker is installed on your machine. If needed, download it from the official website:

• Get Docker

2) Prepare a Dockerfile

A Dockerfile describes your container environment and how to build the image. Place it in the root of your project (or adjust paths accordingly).

Below is a minimal example that copies a prebuilt application JAR and runs it.

FROM eclipse-temurin:21-jdk-alpine

ENV SAMPLE_APP_JAR=Aspose.HTML-for-Java.WebService-on-Docker.jar
ENV ASPOSE_PRODUCT_DIR=aspose-html-for-java
ENV ASPOSE_SAMPLE_APP_DIR=sample-web-service

# 1. Create work directories
ENV WORK_DIR_HOME=/home/${ASPOSE_PRODUCT_DIR}
RUN mkdir -p ${WORK_DIR_HOME}

# 2. Set up app directory and copy the JAR
ENV SERVICE_HOME=${WORK_DIR_HOME}/${ASPOSE_SAMPLE_APP_DIR}
RUN mkdir -p ${SERVICE_HOME} && chmod -R 775 ${SERVICE_HOME}
COPY build/libs/${SAMPLE_APP_JAR} ${SERVICE_HOME}/
ENV APP_PATH=${SERVICE_HOME}/${SAMPLE_APP_JAR}

# 3. Set up assets directory (optional)
# Adjust paths to your project layout and build context.
ENV ASSETS=${SERVICE_HOME}/assets
RUN mkdir -p ${ASSETS} && chmod -R 775 ${ASSETS}
COPY ../../assets/ ${ASSETS}/

# 4. Quick check (optional)
RUN java -version

# 5. Expose service port (used with docker run -p)
EXPOSE 9999

# 6. Run the application
ENTRYPOINT ["java", "-jar", "/home/aspose-html-for-java/sample-web-service/Aspose.HTML-for-Java.WebService-on-Docker.jar"]

3) Install fonts (recommended)

If you convert HTML to PDF/images, install fonts so text renders consistently and layout matches expectations.

Below is an Alpine-based example that installs common font dependencies and shows one way to add Microsoft Core Fonts.

FROM eclipse-temurin:21-jdk-alpine

ENV SAMPLE_APP_JAR=Aspose.HTML-for-Java.WebService-on-Docker.jar
ENV ASPOSE_PRODUCT_DIR=aspose-html-for-java
ENV ASPOSE_SAMPLE_APP_DIR=sample-web-service

ENV WORK_DIR_HOME=/home/${ASPOSE_PRODUCT_DIR}
RUN mkdir -p ${WORK_DIR_HOME}

ENV SERVICE_HOME=${WORK_DIR_HOME}/${ASPOSE_SAMPLE_APP_DIR}
RUN mkdir -p ${SERVICE_HOME} && chmod -R 775 ${SERVICE_HOME}
COPY build/libs/${SAMPLE_APP_JAR} ${SERVICE_HOME}/

ENV ASSETS=${SERVICE_HOME}/assets
RUN mkdir -p ${ASSETS} && chmod -R 775 ${ASSETS}
COPY ../../assets/ ${ASSETS}/

# Install font tools and common fonts
RUN apk add --no-cache \
  fontconfig \
  freetype \
  ttf-dejavu \
  ttf-droid \
  ttf-freefont \
  ttf-liberation \
  ttf-opensans \
  curl \
  cabextract \
  xz \
  unzip \
  msttcorefonts-installer || true

# Optional: manual Microsoft Core Fonts install (Arial example)
RUN mkdir -p /usr/share/fonts/truetype/msttcore && \
  cd /usr/share/fonts/truetype/msttcore && \
  curl -LO http://downloads.sourceforge.net/corefonts/arial32.exe && \
  cabextract -F '*.ttf' arial32.exe && \
  rm -f arial32.exe && \
  fc-cache -f -v

# Verify fonts (optional)
RUN java -version && fc-list | grep -i arial || true

EXPOSE 9999
ENTRYPOINT ["java", "-jar", "/home/aspose-html-for-java/sample-web-service/Aspose.HTML-for-Java.WebService-on-Docker.jar"]

Tips

• If your HTML uses custom fonts, copy them into the image (for example, /usr/share/fonts) and run fc-cache -f -v.
• For easier font installation, consider a Debian/Ubuntu-based image (packages are generally more straightforward than Alpine).

4) Build the Docker image

Before building the image, make sure your application JAR exists (for example, run your build to produce build/libs/*.jar).

Open a terminal in the folder with your Dockerfile and run:

docker build -t my-image .

Replace my-image with any image name you prefer.

5) Run the container

Run the container and map ports from your host to the container:

docker run -p 8080:9999 --rm my-image

• 8080 — port on your host machine
• 9999 — port exposed by the application inside the container
• --rm — automatically removes the container after it stops

6) Verify the container is running

To list active containers:

docker ps

You should see your container in the list, including port mappings.

Conclusion

Running Aspose.HTML for Java in Docker gives you a consistent and reproducible environment for HTML conversion and processing across local development, CI pipelines, and production deployments.

If you see differences in layout or missing glyphs, start by verifying that the container contains all required fonts and that the font cache is rebuilt (fc-cache -f -v).