Run BuildVu with Docker

Table of contents

1. Prerequisites
2. Run BuildVu with Docker
3. Passing JVM flags
4. Wrapping it in a shell alias or script
5. Frequently asked questions
   1. BuildVu can’t find my input file
   2. Why mount the JAR instead of building a custom image?
   3. Do I have to use the eclipse-temurin:25-jre image?
   4. Can I run BuildVu as a web service?
   5. Do I need to install fonts?
   6. Can I convert Office documents?

BuildVu is distributed as a self-contained JAR, so you can run it inside any standard Java image without building a custom Docker image. This page shows how to run BuildVu with Docker by mounting the JAR into the official eclipse-temurin image and treating docker run as a wrapper around java -jar.

This is useful if you want to run BuildVu on a machine that doesn’t have Java installed, or to pin an exact Java version without changing the rest of the system.

Looking to run BuildVu as a REST web service instead? See How to run the BuildVu Docker Image, which uses our prebuilt microservice image.

Prerequisites

• Install Docker
• You must download buildvu-html.jar or buildvu-svg.jar
• A Java 17+ image such as eclipse-temurin:25-jre, which Docker pulls automatically on first run

Run BuildVu with Docker

The command below mounts two things into the container: the BuildVu JAR, and the directory containing your files. Replace /path/to/buildvu-html.jar with the location of the JAR on your machine, and /path/to/data with the directory holding your input files.

docker run --rm \
  -v /path/to/buildvu-html.jar:/app/buildvu-html.jar \
  -v /path/to/data:/data \
  eclipse-temurin:25-jre \
  java -jar /app/buildvu-html.jar /data/input.pdf /data/output

Breaking this down:

• -v /path/to/buildvu-html.jar:/app/buildvu-html.jar mounts the BuildVu JAR into the container at /app/buildvu-html.jar.
• -v /path/to/data:/data mounts your files into the container at /data, so input and output paths are given relative to /data. The converted output is written back to this directory on your machine.
• --rm removes the container once the conversion finishes.

Because both the JAR and your files are mounted at runtime, there is no image to rebuild. To use a different version of BuildVu, just point the first -v at a different JAR.

Windows: use a Windows-style path for the mounts (for example C:\path\to\data:/data), and either put the whole command on one line or replace the \ line-continuation character with a backtick ` (PowerShell) or a caret ^ (Command Prompt).

Linux: files written to the mounted directory will be owned by root. To have the output owned by your own user instead, add --user $(id -u):$(id -g) to the command. This isn’t needed on Docker Desktop for Windows or macOS.

Passing JVM flags

You can pass JVM flags and BuildVu system properties before -jar, exactly as you would when running locally. For example, to increase the heap size:

docker run --rm \
  -v /path/to/buildvu-html.jar:/app/buildvu-html.jar \
  -v /path/to/data:/data \
  eclipse-temurin:25-jre \
  java -Xmx2g -jar /app/buildvu-html.jar /data/input.pdf /data/output

The BuildVu settings and system properties (-D...) you can pass are the same as when running the JAR directly — see Running BuildVu from the command line for full details.

Wrapping it in a shell alias or script

Typing the full command every time is tedious. On Linux and macOS you can wrap it in a shell alias so you only type the BuildVu arguments. This alias uses $(pwd) to mount whichever directory you run it from:

alias buildvu='docker run --rm -v /path/to/buildvu-html.jar:/app/buildvu-html.jar -v "$(pwd)":/data eclipse-temurin:25-jre java -jar /app/buildvu-html.jar'

Then run conversions from any directory with just:

buildvu /data/input.pdf /data/output

Add the alias line to your ~/.bashrc or ~/.zshrc to make it permanent.

For something more portable, save it as a script instead, for example at /usr/local/bin/buildvu:

#!/usr/bin/env bash
docker run --rm \
  -v /path/to/buildvu-html.jar:/app/buildvu-html.jar \
  -v "$(pwd)":/data \
  eclipse-temurin:25-jre \
  java -jar /app/buildvu-html.jar "$@"

Make it executable with chmod +x /usr/local/bin/buildvu, then run conversions from any directory:

buildvu /data/input.pdf /data/output

(These wrappers are Bash/Zsh shorthands. On Windows, run the full docker run command shown above, or create a PowerShell function.)

Frequently asked questions

BuildVu can’t find my input file

Paths are resolved inside the container, not on your host machine. The -v /path/to/data:/data mount makes your files available at /data, so input and output paths must be given relative to /data (for example /data/input.pdf) — not the path the file has on your machine. Make sure the file you want to convert is inside the directory you mounted.

Why mount the JAR instead of building a custom image?

Mounting keeps things simple: there’s no image to build, and you can switch BuildVu versions just by pointing at a different JAR. If you would rather have a self-contained image — for CI or deployment — write a small Dockerfile:

FROM eclipse-temurin:25-jre
COPY buildvu-html.jar /app/buildvu-html.jar
ENTRYPOINT ["java", "-jar", "/app/buildvu-html.jar"]

Build it with docker build -t my-buildvu ., then run it with your files mounted at /data.

Do I have to use the eclipse-temurin:25-jre image?

No. BuildVu requires Java 17 or later, so any image that provides a compatible JRE will work. We default to the Java 25 image, eclipse-temurin:25-jre, because it is small, official and up to date, but you can use an Alpine variant for a smaller image, or another vendor’s Java image — as long as it is Java 17+. See which Java versions BuildVu supports for compatibility details.

Can I run BuildVu as a web service?

This setup runs a single conversion and then exits, which is ideal for scripts and one-off jobs. To run BuildVu as a long-running REST service, use our prebuilt Docker image instead — see How to run the BuildVu Docker Image.

Do I need to install fonts?

No. BuildVu does not use any fonts installed on the system, and does not require fontconfig inside the Docker image.

Can I convert Office documents?

BuildVu converts Office documents by using LibreOffice to pre-convert them to PDF first. The eclipse-temurin image does not include LibreOffice, so Office conversion will not work with this setup. To convert Office documents, either install LibreOffice in a custom image, or use our prebuilt Docker microservice image, which bundles LibreOffice.