Skip to main content

Installation

bkhtmltopdf is developed using Java 21, so before installation, you must ensure that you have JDK 21 or a newer version installed. This guide will walk you through the steps for JDK installation, project download, and application startup.

JDK 21

You can choose any OpenJDK 21 distribution. We recommend using Azul Zulu JDK (open-source, stable) and choosing the portable version (no system-wide installation required).

Download and Installation Steps

  1. Visit the Azul Zulu JDK download page.
  2. Select the version suitable for your operating system (e.g., Windows x64, macOS, or Linux) and download the ZIP/TAR.GZ package.
  3. Extract it to any directory, for example:
    • Windows: C:\java\zulu21
    • macOS/Linux: /opt/java/zulu21
  4. (Optional) Set environment variables:
    • Add the JDK's bin directory to your system's PATH.
    • Set the JAVA_HOME environment variable to point to the JDK root directory (e.g., export JAVA_HOME=/opt/java/zulu21).

Verification

Open a terminal/command prompt and run the following command for verification:

java -version

The output should be similar to:

openjdk version "21.0.x" 2023-xx-xx
OpenJDK Runtime Environment (build 21.0.x+xx-Zulu21.xx.xx-CA)
tip

If you use another JDK (such as Oracle JDK or Amazon Corretto), ensure the version is ≥21.

Download bkhtmltopdf

  1. Visit the GitHub Release page.
  2. Download the latest JAR file, for example, bkhtmltopdf-x.y.z.jar (where x.y.z is the version number, such as 1.0.0).

Save the JAR file to your working directory, for example:

  • Windows: C:\tools\bkhtmltopdf-x.y.z.jar
  • macOS/Linux: ~/tools/bkhtmltopdf-x.y.z.jar

Launch bkhtmltopdf

Assuming you have completed the two steps above, you can now launch the application.

Launch Command

In the terminal/command prompt, navigate to the directory where the JAR file is located and run the following command ( replace JDK_PATH with your JDK installation path, e.g., C:\java\zulu21):

JDK_PATH/bin/java -jar bkhtmltopdf-x.y.z.jar

Examples

  • Windows:
C:\java\zulu21\bin\java -jar C:\tools\bkhtmltopdf-1.0.0.jar
  • macOS/Linux:
/opt/java/zulu21/bin/java -jar ~/tools/bkhtmltopdf-1.0.0.jar

First Launch Notes

  • On the first run, the application will automatically download the JCEF (Java Chromium Embedded Framework) dependency. This may take a few minutes, depending on your network speed.
  • Upon successful startup, you will see logs similar to the following:
Tomcat started on port 8080 (http) with context path '/'
Started Application in 0.792 seconds (process running for 1.195)

Next Steps

Once successfully launched, you can refer to the Quick Start documentation to begin using bkhtmltopdf to generate PDFs. If you encounter any issues, please check the GitHub Issues or provide your logs for feedback.