Skip to main content

Install Apache Hop

Apache Hop has no installer and no server to set up: you download it, unzip it and start it. This guide covers the desktop installation first, then the other ways to run Hop: the command-line tools, Hop Server, the apache/hop Docker image and Hop Web.

You want toUseSection
Design and test pipelines and workflows on your own machineHop GUIInstall Hop GUI
Run pipelines and workflows from scripts, schedulers or CI/CDhop-runCommand-line tools
Run work remotely on a central serverHop ServerRun Hop Server
Run pipelines and workflows in containers or on Kubernetesapache/hop imageRun Hop in Docker
Give a team a browser-based Hop GUI without local installsapache/hop-web imageRun Hop Web
Putki

Putki is built on Apache Hop, and installing it works exactly the same way. Putki provides its own images with security patches applied; those are described in the Putki section.

Before you start: Java 21​

Hop needs a Java runtime, and the official version is Java 21. Check what you have:

java -version

The output should report version 21. If the command is not found, or reports an older version, install a Java 21 runtime first. Oracle Java, Microsoft's OpenJDK builds and OpenJDK work well; the Hop team keeps a list of supported and unsupported runtimes.

Install Hop GUI on your desktop​

Hop runs on Windows, Linux (x86_64 and ARM) and macOS.

  1. Download the client zip from the Apache Hop downloads page.

  2. Unzip it to a folder of your choice. That folder is your Hop installation: it holds the launcher scripts, the config/ folder and the plugins/ folder.

  3. Keep your configuration outside the installation folder (see the next section). Do this once, before you create your first project.

  4. Start Hop GUI:

    hop-gui.bat

    The first start takes a little longer than the ones after it, because Hop scans and registers its plugins.

Keep your configuration outside the installation​

By default Hop stores its configuration, including the list of your projects and environments, in the config/ folder inside the installation. An upgrade is a fresh unzip, so that configuration would stay behind in the old folder. Point Hop at a configuration folder of your own instead.

Hop 2.20 and later set this up for you. Run the following once and restart Hop, or use Tools → Configure Hop environment… in Hop GUI:

hop.bat setup apply --defaults

This sets HOP_CONFIG_FOLDER and HOP_AUDIT_FOLDER to folders in your user profile. See Hop setup for what it changes and how to undo it.

Earlier versions: set the HOP_CONFIG_FOLDER environment variable yourself, to a folder outside the installation.

Search for Environment Variables in the Start menu, open Edit the system environment variables, and add a user variable named HOP_CONFIG_FOLDER with a folder such as C:\hop-config as its value. Start a new command prompt so the variable is picked up.

If the folder is new, copy the contents of the installation's config/ folder into it first, so your existing projects and settings come along.

The command-line tools​

The same folder holds the command-line tools. On Windows they end in .bat, on Linux and macOS in .sh:

ScriptWhat it does
hop-runRuns a pipeline or workflow without the GUI: from a script, a scheduler or a CI/CD job
hop-confCreates and manages projects, environments and configuration
hop-serverStarts Hop Server
hop-searchSearches the metadata in a project
hop-encryptEncrypts passwords for use in metadata and configuration files
hop-importConverts Pentaho/Kettle jobs and transformations to Apache Hop

For example, to run a workflow in the project my-hop-project with the local run configuration:

hop-run.bat -j my-hop-project -f C:\path\to\my-hop-project\flights-processing.hwf -r local

-j selects the project, -f the file to run and -r the run configuration. See hop-run and hop-conf in the Apache Hop manual for every option.

Run Hop Server​

Hop Server runs pipelines and workflows sent to it by Hop GUI, hop-run or its REST API. Start it from the installation folder with the address and port to listen on:

hop-server.bat 0.0.0.0 8080

Its status page is then available at http://<server>:8080. The default username and password are both cluster: change them before the server is reachable by anyone else. For production, Hop Server usually runs in the apache/hop Docker image instead (see the next section). See Hop Server for configuration files, SSL and the REST API.

Run Hop in Docker​

The apache/hop image runs in two modes:

  • Short-lived: runs one pipeline or workflow and stops. This is how most production deployments run Hop, from a scheduler or as a Kubernetes job.
  • Long-lived: when you don't tell it which file to run, it starts Hop Server and waits for work.

To run a workflow from a project on your machine, mount the project folder and tell the container which project, file and run configuration to use:

docker run -it --rm \
  --env HOP_LOG_LEVEL=Basic \
  --env HOP_PROJECT_FOLDER=/files \
  --env HOP_PROJECT_NAME=my-hop-project \
  --env HOP_FILE_PATH='${PROJECT_HOME}/flights-processing.hwf' \
  --env HOP_RUN_CONFIG=local \
  -v /path/to/my-hop-project:/files \
  apache/hop:latest

The container creates the project from HOP_PROJECT_FOLDER and HOP_PROJECT_NAME, runs the file in HOP_FILE_PATH with the run configuration in HOP_RUN_CONFIG, prints the log and exits. Use a specific version tag instead of latest in production, so a new release never changes what runs without you deciding to.

The image reads more variables, for environments, parent projects and extra JDBC drivers among others. See Hop in Docker for the full list.

Run Hop Web​

Hop Web is the same Hop GUI, running in a browser. It is useful for shared development environments, or when installing Hop on every laptop is not an option. Start it with the apache/hop-web image:

docker run -p 8080:8080 apache/hop-web:latest

Then open http://localhost:8080/ui.

Hop Web is a long-lived application where people save their work, so project files and Hop configuration must live on a mounted folder or volume, not only inside the container. See Hop Web in Docker for which folders to persist, and Hop Web for adding users and passwords.

Upgrade to a new version​

  • Desktop: download and unzip the new version next to the old one. If your configuration lives outside the installation (see above), the new version picks up your projects and environments straight away. Hop GUI may open the default project first; select your own project from the project list.
  • Docker: pull the new image tag and replace the container. Keep projects and configuration on mounted folders, never only inside the container, so nothing is lost when it is replaced.

Next steps​