holoscan run - simplifies running a packaged Holoscan application by reducing the number of arguments required compared to docker run. In addition, it follows the guidelines of HAP specification when launching your packaged Holoscan application.
When running a packaged Holoscan application on Kubernetes or other service providers, running Docker with non root user, and running Holoscan CLI run command where the logged-on user’s ID is different, ensure to specify the USER ID that is used when building the application package.
For example, include the securityContext when running a Holoscan packaged application with UID=1000 using Argo:
spec:
securityContext:
runAsUser: 1000
runAsNonRoot: true
holoscan run [--help|-h] [--log-level|-l {DEBUG,INFO,WARN,ERROR,CRITICAL}] [--address ADDRESS] [--driver] [--input|-i INPUT] [--output|-o OUTPUT] [--fragments|-f FRAGMENTS] [--worker] [--worker-address WORKER_ADDRESS] [--config CONFIG] [--network|-n NETWORK] [--nic NETWORK_INTERFACE] [--use-all-nics] [--render|-r] [--quiet|-q] [--shm-size][--terminal] [--device] [--gpu] [--uid UID] [--gid GID]image:[tag]
To run a packaged Holoscan application:
holoscan run -i /path/to/my/input -o /path/to/application/generated/output my-application:1.0.1
image:[tag]
Name and tag of the Docker container image to execute.
[--address ADDRESS]
Address ([<IP or hostname>][:<port>]) of the App Driver. If not specified, the App Driver uses the default host address (0.0.0.0) with the default port number (8765).
For example:
--address my_app_network
--address my_app_network:8765
Ensure that the IP address is not blocked and the port is configured with the firewall accordingly.
[--driver]
Run the App Driver on the current machine. Can be used together with the [--worker] option to run both the App Driver and the App Worker on the same machine.
[--input|-i INPUT]
Specifies a directory path with input data for the application to process.
When specified, a directory mount is set up to the value defined in the environment variable HOLOSCAN_INPUT_PATH.
Ensure that the directory on the host is accessible by the current user or the user specified with –uid.
Use the host system path when running applications inside Docker (DooD).
[--output|-o OUTPUT]
Specifies a directory path to store application-generated artifacts.
When specified, a directory mount is set up to the value defined in the environment variable HOLOSCAN_OUTPUT_PATH.
Ensure that the directory on the host is accessible by the current user or the user specified with –uid.
[--fragments|-f FRAGMENTS]
A Comma-separated names of the fragments to be executed by the App Worker. If not specified, only one fragment (selected by the App Driver) will be executed. all can be used to run all the fragments.
[--worker]
Run the App Worker.
[--worker-address WORKER_ADDRESS]
The address ([<IP or hostname>][:<port>]) of the App Worker. If not specified, the App Worker uses the default host address (0.0.0.0) with a randomly chosen port number between 10000 and 32767 that is not currently in use.
This argument automatically sets the HOLOSCAN_UCX_SOURCE_ADDRESS environment variable if the worker address is a local IP address. Refer to Environment Variables for Distributed Applications for details.
For example:
--worker-address my_app_network
--worker-address my_app_network:10000
Ensure that the IP address is not blocked and the port is configured with the firewall accordingly.
[--config CONFIG]
Path to the application configuration file. If specified, it overrides the embedded configuration file found in the environment variable HOLOSCAN_CONFIG_PATH.
[--network|-n NETWORK]
The Docker network that the application connects to for communicating with other containers.
The Runner use the host network by default if not specified. Otherwise, the specified value
is used to create a network with the bridge driver.
For advanced usages,
first create a network using docker network create and pass the name of the network to the --network option.
Refer to Docker Networking documentation for additional details.
[--nic NETWORK_INTERFACE]
Name of the network interface to use with a distributed multi-fragment application.
This option sets UCX_NET_DEVICES environment variable with the value specified and is required when
running a distributed multi-fragment application across multiple nodes.
See UCX Network Interface Selection for details.
[--use-all-nics]
When set, this option allows UCX to control the selection of network interface cards for data
transfer. Otherwise, the network interface card specified with ‘–nic’ is used.
This option sets the environment variable UCX_CM_USE_ALL_DEVICES to y. (default: False)
When this option is not set, the CLI runner always sets UCX_CM_USE_ALL_DEVICES to n.
[--render|-r]
Enable graphic rendering from your application. Defaults to False.
[--quiet|-q]
Suppress the STDOUT and print only STDERR from the application. Defaults to False.
[--shm-size]
Sets the size of /dev/shm. The format is <number(int,float)>[MB|m|GB|g|Mi|MiB|Gi|GiB].
Use config to read the shared memory value defined in the app.json manifest.
By default, the container is launched using --ipc=host with host system’s /dev/shm mounted.
[--terminal]
Enters terminal with all configured volume mappings and environment variables.
[--device]
Map host devices into the application container.
By default, the CLI searches the /dev/ path for devices unless the specified string starts with /.
For example:
# mount all AJA capture cards
--device ajantv*
# mount AJA capture card 0 and 1
--device ajantv0 ajantv1
# mount V4L2 video device 1 and AJAX capture card 2
--device video1 --device /dev/ajantv2
When using the --device option, append -- after the last item to avoid misinterpretation by the CLI.
E.g.
holoscan run --render --device ajantv0 video1 -- my-application-image:1.0
[--gpu]
Override the value of the NVIDIA_VISIBLE_DEVICES environment variable with the default value set to
the value defined in the package manifest file or all if undefined.
Refer to the GPU Enumeration page for all available options.
The default value is nvidia.com/igpu=0 when running a HAP built for iGPU on a system with both iGPU and dGPU,
A single integer value translates to the device index, not the number of GPUs.
[--uid UID]
Run the application with the specified user ID (UID). Defaults to the current user’s UID.
[--gid GID]
Run the application with the specified group ID (GID). Defaults to the current user’s GID.
The Holoscan Application supports various environment variables for configuration. Refer to Environment Variables for Distributed Applications for details.