Run FormVu with Docker

Table of contents

1. Prerequisites
2. Run FormVu with Docker
3. Passing JVM flags
4. Wrapping it in a shell alias or script
5. Frequently asked questions
   1. FormVu 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 FormVu as a web service?
   5. Do I need to install fonts?

FormVu 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 FormVu 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 FormVu 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 FormVu as a REST web service instead? See How to run the FormVu Docker Image, which uses our prebuilt microservice image.

Prerequisites

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

Run FormVu with Docker

The command below mounts two things into the container: the FormVu JAR, and the directory containing your files. Replace /path/to/formvu.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/formvu.jar:/app/formvu.jar \
  -v /path/to/data:/data \
  eclipse-temurin:25-jre \
  java -jar /app/formvu.jar /data/input.pdf /data/output

Breaking this down:

• -v /path/to/formvu.jar:/app/formvu.jar mounts the FormVu JAR into the container at /app/formvu.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 FormVu, 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 FormVu system properties before -jar, exactly as you would when running locally. For example, to increase the heap size:

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

The FormVu settings and system properties (-D...) you can pass are the same as when running the JAR directly — see Running FormVu 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 FormVu arguments. This alias uses $(pwd) to mount whichever directory you run it from:

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

Then run conversions from any directory with just:

formvu /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/formvu:

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

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

formvu /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

FormVu 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 FormVu 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 formvu.jar /app/formvu.jar
ENTRYPOINT ["java", "-jar", "/app/formvu.jar"]

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

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

No. FormVu 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 FormVu supports for compatibility details.

Can I run FormVu as a web service?

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

Do I need to install fonts?

FormVu requires fontconfig to be present, but does not need any font files to be installed. The eclipse-temurin:25-jre image already includes fontconfig, so this works out of the box. If you switch to a minimal base image that omits fontconfig (some Alpine variants, for example), install it — for example apk add fontconfig — or FormVu may fail to start.