Vert.x - The launcher run command

About

The run command (Code) is a command of the launcher.

It will:

• create a instance of vert.x
• and deploy a verticle (called the main verticle) in it.

Example

Vertx command line

Via the vertx command line

cd /verticles # the location of the verticle jar
vertx run io.vertx.sample.RandomGeneratorVerticle 
    -cp /verticles/MY_VERTICLE.jar 

Fat jar

Via a fat jar

java -jar my-vertx-fat.jar run \
    -cluster \
    -conf myconf.json \
    -cp path/to/dir/conf/cluster_xml

Docker

Via the docker vertx-exec image

docker run -i -t -p 8080:8080 \ 
    -v $PWD:/verticles vertx/vertx3-exec \  
    run io.vertx.sample.RandomGeneratorVerticle \ 
    -cp /verticles/MY_VERTICLE.jar 

Syntax

Runs a Verticle called <main-verticle> in its own instance of vert.x.

(launcher) run \
    [-cp <classpath>] \ 
    [--cluster] \
    [--cluster-host <host>] \
    [--cluster-port <port>] \
    [--cluster-public-host <public-host>] \
    [--cluster-public-port <public-port>] \
    [--conf <config>]  \
    [--ha] \
    [--hagroup <group>] \
    [--instances <instances>] \
    [--on-redeploy <cmd>] \
    [--options <options>] \ #vertx options
    [--quorum <q>] \
    [--redeploy <includes>] \
    [--redeploy-grace-period <period>] \
    [--redeploy-scan-period <period>] \
    [--redeploy-termination-period <period>]  \
    [--worker] \
    main-verticle

where:

Launcher

• launcher is a launcher or a custom launcher wrapper such as
  • a fat_jar
  • a docker image
  • the vertx_command_line (only for the default launcher)
• cp provides an extra classpath
• --launcher-class default to io.vertx.core.Launcher but you can set a main
• <main-verticle> defines the main verticle to deploy, it can be
  • a fully qualified class name
  • or a file.

Cluster

• cluster If specified then the vert.x instance will form a cluster with any other vert.x instances on the network.
• --cluster-host <host> host to bind to for cluster communication. If this is not specified vert.x will attempt to choose one from the available interfaces.
• --cluster-port <port> Port to use for cluster communication. Default is 0 which means choose a spare random port.
• --cluster-public-host <public-host> - Public host to bind to for cluster communication. If not specified, Vert.x will use the same as cluster host.
• --cluster-public-port <public-port> - Public port to use for cluster communication. Default is -1 which means same as cluster port.

Vertx

• --options <options> - Specifies the Vert.x options. (Json file or String)

There is a mapping between system properties and Vert.x Options as in:

-Dvertx.options.workerPoolSize=20 

Verticle

• --conf <config> Specifies configuration that should be provided to the verticle. (Json file or string)
• --instances <instances> Specifies how many instances of the verticle will be deployed. Defaults to 1.
• --worker If specified then the verticle is a worker verticle.

The deployment options of the main verticle can also be configured from system properties:

-Dvertx.deployment.options.worker=true
-Dvertx.deployment.options.instances=2 # 1 by default

High Avaibility

• --ha If specified the verticle will be deployed as a high availability (HA) deployment.
• --hagroup <group> used in conjunction with -ha this specifies the HA group this node will join. (Defaults to __DEFAULT__)
• --quorum <q> specifies the minimum number of nodes in the cluster for any HA deploymentIDs to be active. Defaults to 1.

Hot deployment

Vert.x - Hot reloading / Live redeploy

• --on-redeploy <cmd> Optional shell command executed when a redeployment is triggered.
• --redeploy <includes> Enable automatic redeployment of the application. This option takes a set on includes as parameter indicating which files need to be watched. Patterns are separated by a comma.
• --redeploy-grace-period <period> When redeploy is enabled, this option configures the grace period between 2 redeployments. The time is given in milliseconds. 1000 ms by default.
• --redeploy-scan-period <period> When redeploy is enabled, this option configures the file system scanning period to detect file changes. The time is given in milliseconds. 250 ms by default.
• --redeploy-termination-period <period> When redeploy is enabled, this option configures the time waited to be sure that the previous version of the application has been stopped. It is useful on Windows, where the 'terminate' command may take time to be executed.The time is given in milliseconds. 0 ms by default.