Deployer Substitutions

When you deploy modules or bootstrap, the Deploy tool will make substitutions. This is most frequently used for adjusting the configuration during bootstrapping, but can also be used to make some environment-specific changes in the source code itself.

Note that as of Roxy 1.5, properties will be substituted in reverse-alphabetical order, e.g. reverse order compared to ml {env} info -- longer properties will effectively match before shorter ones, fixing any earlier problems with this.

Bootstrap substitutions

The deploy/*.properties files set up properties used to configure the app servers, databases and forests for your project. A simple example of this is the modules-root property. The deploy/ml-config.xml file includes this element, inside of the app-server definition you will use to access your application:

<root>${modules-root}</root>

The Deploy tool sees this in the configuration and replaces @ml.modules-root, or ${modules-root} with the value given in the properties file. (It will use the value in build.properties unless the setting is overridden in an environment-specific properties file.) You can use properties defined in the deploy/*.properties files in ml-config.xml, pipeline-config.xml (if you're using CPF) as well as in the properties files themselves.

Using properties in source code

Roxy provides an XQuery configuration module in src/app/config/config.xqy. The Roxy Deploy tool will look for substitutions there as well. For example, suppose you want your source code to know what environment it's running in. This will do it:

declare variable $c:ENV := "${environment}";

After running "ml dev deploy modules", this line will become:

declare variable $c:ENV := "dev";

Note that this feature requires using a modules database, not the filesystem. Note also that you can override which file is treated that way, by specifying a property called application-conf-file. It accepts a comma-separated list of file paths.

Custom properties

Besides the properties already in the deploy/*.properties files, you can add your own. Suppose that your application will make calls to another service. Rather than hard-coding the service URL, set up a property. That way you can call different versions of the service from different environments:

deploy/local.properties:

service-url=http://some.useful.service:8080/do-something

deploy/prod.properties:

service-url=http://faster.useful.service:8080/do-something

src/app/config/config.xqy:

declare variable $SERVICE-URL := "${service-url}";

When you use this feature, remember that you need to end up with valid XQuery. Dealing with strings and putting the substitutions in quotes should keep you safe.

List of Properties

Properties defined in the deploy/*.properties files are accessible using the @ml. prefix, or by wrapping them in ${..}. There are various properties available out of the box, and you can add as many as you like yourself. You can use the following command to get a list of all available properties for any specific environment:

$ ./ml {env} info