This topic is under construction for the 24.3 (March 2024) release of LabKey Server. For current documentation of this feature, click here.

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.


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>/build/deploy/startup directory, where <LABKEY_HOME> is the root of your enlistment. Create this directory in your enlistment if it does not exist.

One or more properties files can be defined and placed in this startup directory. 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.

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_application.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_application.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 properties only when the server first starts on a new database.
  • startup: Apply the properties every time the server starts.

Create and Apply Property Files

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

Sample 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

All Available Startup Properties (Premium Feature)

On a Premium Edition of LabKey Server, you can access a list of the currently available startup properties and how they are used.

  • Select (Admin) > Site > Admin Console.
  • Under Premium Features, click Available Startup Properties.
  • Categories are listed in alphabetical order and descriptions help make it easier to find the desired property.

Related Topics

For more about options that can be controlled with a startup properties file:

Was this content helpful?

Log in or register an account to provide feedback


previousnext
 
expand allcollapse all