Remote run with export resources

Hop Server runs on a machine — or in a stock apache/hop long-lived container — without a project of its own. A client (Hop Gui, hop-run, an Airflow worker that has a Hop client) executes a workflow or pipeline with a Remote run configuration and Export linked resources to server enabled. Everything Hop can pack is sent to the server in a ZIP.

See Deploying Hop Server for how this compares to the other patterns.

Environment configuration happens on the client. The server never reads your environment JSON files.

How the ZIP is built

When export resources is enabled, Hop walks the parent pipeline or workflow and every referenced pipeline or workflow (mappings, workflow actions, metadata-referenced files such as a Pipeline Log). It then:

serializes the client’s project metadata to metadata.json inside the ZIP
rewrites sibling Hop files to ${Internal.Entry.Current.Folder}/…
rewrites named data folders to ${DATA_PATH_n}/…
adds the execution configuration XML, including the variables that were resolved on the client
sends the ZIP to the server, which runs from the archive without unzipping it into a project home

The remote run configuration has two folder fields that matter as soon as you touch anything that is not a .hpl / .hwf file:

Option What to put there

Option	What to put there
Named resources reference source folder	Typically `${PROJECT_HOME}`
Named resources reference target folder	A directory that exists on the server (or is mounted there)

Named resources reference source folder

Typically ${PROJECT_HOME}

Named resources reference target folder

A directory that exists on the server (or is mounted there)

Result: ${DATA_PATH_1} is set to the target mapping of that folder, for example /data/incoming.

If you leave the target empty, ${DATA_PATH_n} keeps the client’s absolute path, which is almost never valid on the server.

The same options are documented on the Remote pipeline and Remote workflow pages.

What is not in the ZIP

Export resources is easy to get wrong. File locations lose their meaning once they have been rewritten into a ZIP, and extra dependencies are not sent.

Environment JSON files are not sent. Enable the environment on the client (hop-run.sh -e prod …) so the variables are already in the execution configuration.
Extra configuration files (.properties, JSON or Avro schemas, templates, snippets of hop-config.json) are not sent unless a transform or action implements exportResources() for that filename. Many do not.
JDBC drivers, plugins and native libraries are never sent. Install them on the server (or in the server image) yourself.
Large data files are renamed, not packed. Stage them on the server or on a shared VFS (S3, NFS, …) and map the folder.
Only transforms and actions that implement exportResources participate. A "Write to file" transform with a hardcoded laptop path will fail on the server.

Practical rules:

Express every path as a variable (${PROJECT_HOME}, ${DATA_IN}, …), never as a developer laptop path.
Prefer environment variables over sidecar files if you must use this pattern.
Pre-stage shared files on the server and set the named-resource target folder to that location.
If the project has many file dependencies, use a project image or a git checkout instead.

The client

The environment already references its project, so -e is enough. You do not pass -j as well.

hop-run.sh -e prod \
  -r remote-on-server \
  -f '{openvar}PROJECT_HOME{closevar}/main.hwf'

remote-on-server is a Remote run configuration in the project metadata:

Hop Server host, port and credentials
Export linked resources to server? enabled
Named resources source folder: ${PROJECT_HOME}
Named resources target folder: a path that exists on the server, for example /data/project

Hop Gui uses the same run configuration. That is the usual way to try a shared test server from a laptop.

Apache Airflow

This is not the short-lived apache/hop container how-to. That page runs hop-run inside Docker with a local engine and never talks to Hop Server.

To drive a Hop Server from Airflow you have two honest options:

Give the Airflow worker a Hop client (installed on the worker, or a thin image that contains Hop) and call hop-run with the remote run configuration above.
Stay on the short-lived-container how-to and skip Hop Server entirely.

A DAG task that shells out to hop-run looks like this:

from airflow.operators.bash import BashOperator

run_on_hop_server = BashOperator(
    task_id="run_on_hop_server",
    bash_command=(
        "hop-run.sh -e prod "
        "-r remote-on-server "
        "-f '{openvar}PROJECT_HOME{closevar}/main.hwf'"
    ),
)

The worker must have HOP_CONFIG_FOLDER (or a Hop install whose config/hop-config.json already lists the project and the prod environment) and network access to the server.

The server

The server does not need the project.

Linux, macOS
Docker

./hop-server.sh 0.0.0.0 8080

docker run -d --name hop-server \
  -p 8080:8080 \
  -e HOP_SERVER_USER=hop-admin \
  -e HOP_SERVER_PASS=change-me \
  apache/hop:<version>

Do not set HOP_PROJECT_* on this container. The project arrives in the ZIP.

The server does need:

a Hop version compatible with the client (same release is the safe choice)
the same JDBC drivers and extra plugins the project uses
the named-resource target directories (they can be empty if you only send Hop files)
network reachability from the client
credentials and, in production, TLS — see SSL configuration

Web services look up metadata on the server. They will not see the client’s project unless you also set <metadata_folder> / HOP_SERVER_METADATA_FOLDER. Do not mix the two patterns by accident. If you need web services, put the project on the server with an image or a git checkout.