Run JDeli with Docker

Table of contents

1. Prerequisites
2. Run JDeli with Docker
3. Passing JVM flags
4. Wrapping it in a shell alias or script
5. Frequently asked questions
   1. JDeli 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?

JDeli 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 JDeli 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 JDeli on a machine that doesn’t have Java installed, or to pin an exact Java version without changing the rest of the system.

Prerequisites

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

Run JDeli with Docker

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

Breaking this down:

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

docker run --rm \
  -v /path/to/jdeli.jar:/app/jdeli.jar \
  -v /path/to/data:/data \
  eclipse-temurin:25-jre \
  java -Xmx2g -jar /app/jdeli.jar --convert "png" "/data/input.jpg" /data/output

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

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

Then run conversions from any directory with just:

jdeli --convert "png" "/data/input.jpg" /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/jdeli:

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

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

jdeli --convert "png" "/data/input.jpg" /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

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

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

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

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