Server Startup Properties: /Documentation/Archive/24.3

Server Startup Properties

Some of the initial configuration and startup steps of bootstrapping LabKey Server, i.e. launching a new server on a new database, can be performed automatically by creating a properties file that is applied at startup. Using these startup properties is not required.

Using Startup Property Files
Startup Properties File Format
Create and Apply Property Files
Example Startup Properties
Using System Properties to Specify Startup Properties
Startup Properties Admin Page (Premium Feature)

Configuration steps which can be provided via the startup properties file include, but are not limited to:

Some site settings, such as file root and base server URL
Script engine definitions, such as automatically enabling R scripting
User groups and permission roles
Custom content for the home page

Using Startup Property Files

Startup property files are named with a .properties extension and placed in the <LABKEY_HOME>/startup directory. Create it if it does not exist. One or more properties files can be defined and placed in this location. The files are applied in reverse-alphabetical order. Any property defined in two such files will retain the "last" setting applied, i.e. the one in the file that is "alphabetically" first.

Startup properties are separate from the "application.properties" file responsible for much of the basic configuration. There is no overlap between what is set in the application.properties file and what can be set via startup properties. Learn more here:

Set Application Properties

To control specific ordering among files, you could name multiple .properties files with sequential numbers, ordered starting with the one you want to take precedence. For instance, you might have:

01_important.properties: applied last
02_other.properties
...
99_default.properties: applied first

In this example, anything specified in "99_default.properties" will be overridden if the same property is also defined in any lower-numbered file. All values set for properties in the file "01_important.properties" will override any settings included in other files.

Startup Properties File Format

The properties file is a list of lines setting various properties. The format of a given line is:

<optional scope>.<name>;<optional modifier> = <value>

For example, to emulate going to the "Look and Feel Settings", then setting the "initial" "systemEmailAddress" to be "username@mydomain.com", you would include this line:

LookAndFeelSettings.systemEmailAddress;bootstrap=username@mydomain.com

Modifier Options

The "<optional modifier>" can be one of the following:

;bootstrap: (default) Apply the value only when the server first starts on a new database. On subsequent starts, a ;bootstrap property will be ignored.
;startup: Apply the value to this property every time the server starts.

Create and Apply Property Files

If it does not exist, create the directory: <LABKEY_HOME>/startup
Create a .properties file, such as 99_default.properties
Add the desired content.
Save the file, ensuring it maintains a .properties extension.
Restart your server on a new database.

Example Startup Properties

LookAndFeelSettings.systemEmailAddress = {systemEmail}

SiteSettings.baseServerURL = {baseServerUrl} SiteSettings.exceptionReportingLevel = HIGH SiteSettings.usageReportingLevel = ON SiteSettings.sslRequired = true

Authentication.DefaultDomain = {defaultDomain}

#Ensure the user exists and assign ApplicationAdminRole UserRoles.{email} = org.labkey.api.security.roles.ApplicationAdminRole

#Script Engine Definition ScriptEngineDefinition.R.name;bootstrap = R Scripting Engine ScriptEngineDefinition.R.languageName = R ScriptEngineDefinition.R.languageVersion = {version} ScriptEngineDefinition.R.extensions = R,r ScriptEngineDefinition.R.exePath = {exePath} ScriptEngineDefinition.R.exeCommand = CMD BATCH --slave ScriptEngineDefinition.R.outputFileName = ${scriptName}.Rout

Using System Properties to Specify Startup Properties

Using .properties files is the most common way to specify startup properties, however, startup properties can also be provided via system properties. In other words, -D parameters passed on the Java command line. To be recognized, these system properties must be prefixed with "labkey.prop.". Examples:

-Dlabkey.prop.LookAndFeelSettings.themeName;startup=Seattle "-Dlabkey.prop.LookAndFeelSettings.systemShortName;startup=LabKey ${releaseVersion} running on ${databaseProductName} against ${databaseName}: ${servletConfiguration}"

Note that double quoting the property may be necessary if the value contains spaces.

Startup properties specified via system properties have precedence over all properties files.

Startup Properties Admin Page (Premium Feature)

On a Premium Edition of LabKey Server, you can use the Startup Properties admin page to view startup properties that were applied in the current server session and to access a list of the currently available startup properties and how they are used.

Select (Admin) > Site > Admin Console.
Under Premium Features, click Startup Properties.
Startup properties and their values that were provided while starting up the server are shown first.
All available startup properties, their descriptions, and valid values are listed next. Categories are listed in alphabetical order.

LabKey Support

LabKey Support