2.2. Specifying the OpenIDM Startup Configuration

By default, OpenIDM starts up with the configuration and script files that are located in the openidm/conf and openidm/script directories, and with the binaries that are in the default install location. You can launch OpenIDM with a different configuration and set of script files, and even with a different set of binaries, in order to test a new configuration, managed multiple different OpenIDM projects, or to run one of the included samples.

The startup.sh script enables you to specify the following elements of a running OpenIDM instance.

  • project location (-p)

    The project location specifies the configuration and default scripts with which OpenIDM will run.

    If you specify the project location, OpenIDM does not try to locate configuration objects in the default location. All configuration objects and any artifacts that are not in the bundled defaults (such as custom scripts) must be provided in the project location. This includes everything that is in the default openidm/conf and openidm/script directories.

    The following command starts OpenIDM with the configuration of sample 1: 

    $ ./startup.sh -p /path/to/openidm/samples/sample1

    If an absolute path is not provided, the path is relative to the system property, user.dir. If no project location is specified, OpenIDM is launched with the default configuration in /path/to/openidm/conf.

  • working location (-w)

    The working location specifies the directory to which OpenIDM writes its cache. Specifying a working location separates the project from the cached data that the system needs to store. The working location includes everything that is in the default openidm/db and openidm/audit, openidm/felix-cache, and openidm/logs directories.

    The following command specifies that OpenIDM writes its cached data to /Users/admin/openidm/storage: 

    $ ./startup.sh -w /Users/admin/openidm/storage

    If an absolute path is not provided, the path is relative to the system property, user.dir. If no working location is specified, OpenIDM writes its cached data to openidm/db and openidm/logs.

  • startup configuration file (-c)

    A customizable startup configuration file (named launcher.json) enables you to specify how the OSGi Framework is started.

    If no configuration file is specified, the default configuration (defined in /path/to/openidm/bin/launcher.json) is used. The following command starts OpenIDM with an alternative startup configuration file: 

    $ ./startup.sh -c /Users/admin/openidm/bin/launcher.json

    You can modify the default startup configuration file to specify a different startup configuration.

    The customizable properties of the default startup configuration file are as follows:

    • "location" : "bundle" - resolves to the install location. You can also load OpenIDM from a specified zip file ("location" : "openidm.zip") or you can install a single jar file ("location" : "openidm-system-2.1.jar").

    • "includes" : "**/openidm-system-*.jar" - the specified folder is scanned for jar files relating to the system startup. If the value of "includes" is *.jar, you must specifically exclude any jars in the bundle that you do not want to install, by setting the "excludes" property.

    • "start-level" : 1 - specifies a start level for the jar files identified previously.

    • "action" : "install.start" - a period-separated list of actions to be taken on the jar files. Values can be one or more of "install.start.update.uninstall".

    • "config.properties" - takes either a path to a configuration file (relative to the project location) or a list of configuration properties and their values. The list must be in the format "string":"string", for example: 

                 "config.properties" :
 	           {
 	               "property" : "value"
 	           },

    • "system.properties" - takes either a path to a system.properties file (relative to the project location) or a list of system properties and their values. The list must be in the format "string":"string", for example: 

                 "system.properties" :
 	           {
 	               "property" : "value"
 	           },

    • "boot.properties" - takes either a path to a boot.properties file (relative to the project location) or a list of boot properties and their values.The list must be in the format "string":object, for example: 

                 "boot.properties" :
 	           {
 	               "property" : true
 	           },

By default, properties files are loaded in the following order, and property values are resolved in the reverse order:

  1. system.properties

  2. config.properties

  3. boot.properties

If both system and boot properties define the same attribute, the property substitution process locates the attribute in boot.properties and does not attempt to locate the property in system.properties.

You can use variable substitution in any .json configuration file with the install, working and project locations described previously. The following properties can be substituted:

install.location
install.url
working.location
working.url
project.location
project.url

Property substitution takes the following syntax:

&{launcher.property}

For example, to specify the location of the OrientDB database, you can set the dbUrl property in repo.orientdb.json as follows: 

"dbUrl" : "local:&{launcher.working.location}/db/openidm",

The database location is then relative to a working location defined in the startup configuration.