Configuration

With Nextmv SDK, custom models have the ability to expose variables as options that can be configured at runtime. The set of values defined for these options is called configuration. There are multiple ways that configuration can be defined for your custom model, and within Nextmv Platform there is an order of operations that dictates the hierarchy for which configuration values take precedence.

Configuration types

Default configuration

A default value should always be set when you are defining configuration variables in your custom model. If no configuration is found for this option at run time, the default value will be used.

Nextmv CLI sdk run

When using the sdk run command, options can be configured with either command line flags or environment variables. These options will be parsed by the CLI runner and passed to your custom model. If both a flag and environment variable is set for the same option, the flag will override the environment variable. For more information see the sdk run subcommand reference and the CLI runner and solver options reference.

nextmv sdk run . -- \
  -runner.input.path="./input.json" \
  -solve.duration=10s

Nextmv CLI app run

When using the app run command, options can be configured with the --options flag. These options will be parsed at runtime in the cloud and passed to your custom model. For more information see the app run subcommand reference.

nextmv app run \
  --app-id my-app-id
  --input "./input.json"
  --options solve.duration=10s

Instance config

Configuration can also be set for an instance, and any time this instance is used for a run this configuration will be applied. The configuration for an instance is defined as a set of key value pairs where the key is the configuration option and the value is the configuration option value.

nextmv app instance create \
  --app-id "farm-share-delivery" \
  --version-id "v1-release" \
  --instance-id "prod-duration-10s" \
  --name "Production with 10s duration" \
  --options solve.duration=10s

Input payload

When you submit an input file to the HTTPS API /runs endpoint, you can include an options block that specifies configuration for that run. Each configuration option is defined as a property within the options object where the key is the option name and the value is the option value.

{
  "input": {
    ...
  },
  "options": {
    "solve.duration": "10s"
  }
}

Hierarchy

There is a precedence for how configuration is applied for local runs (nextmv sdk run) and remote runs (nextmv app run & HTTP API). The hierarchy for each is described below.

Local runs

1. CLI flag
2. Environment variable
3. Default model value

Remote runs

1. Input payload (if using HTTPS API endpoint)
2. CLI flag (if using Nextmv CLI)
3. Instance config
4. Default model value

So for example if you create a new run with input that specifies duration=3s in the options block of that input file, and you use an instance that has a configration set for duration=5s, and the executable binary of the version for that instance has a default configuration of duration=10s, the duration for that run will be 3s. If the options block were removed from the input, the duration would be 5s. If a different instance was used for the run that had no configuration set, and there were no options specified in the input, the duration would be 10s.

Subscribed apps

Apps that are subscribed to marketplace apps can configure any option that the marketplace app exposes using any of the methods described here. To see a list of options that are available for the Nextmv Routing app see the Vehicle routing options reference