Staging servers are used for many different reasons, including:

• Ensuring that an upgrade of LabKey Server does not break any customization.
• Testing new modules, views, or queries being developed.
• Running usage scenarios on test data prior to launching to a large group of users.

Overview

This topic outlines some recommended settings to change when configuring a staging server. Not all possible changes are listed here, but this subset is the most useful. Doing things like changing the color scheme on the staging server will help users know which environment they are working on and avoid inadvertent changes to the production environment.

• Change the Server GUID
• Change the Site Settings
• Change the Look and Feel
• Other settings (For Advanced Users)

Considerations

1. The specific SQL statements shown in this topic are for PostgreSQL databases. For MSSQL or other databases, the syntax will be similar but not identical.
2. If you use SQL statements to make the changes suggested on this page, make them after you restore the database on the staging server but before you start LabKey Server there.

Change the Server GUID

Summary: The Server GUID is stored in the database, but can be overridden with one specified in the LabKey XML configuration file (labkey.xml or ROOT.xml). Assigning your staging server a unique Server GUID ensures that any exception reports received by LabKey developers are accurately attributed to the server (staging vs. production) that produced the errors.

Background: The Server GUID is a Global Unique Identifier for each running server. By default, LabKey Servers periodically communicate information, including details about exceptions raised, back to LabKey developers. LabKey groups this information by GUID of each server.

This GUID name should be descriptive, obvious, and unique, particularly in the case of a deployment involving multiple running servers, such as production, staging, and potentially others for test or disaster recovery. For example, if your organization's production server GUID is "Biotopia Server", your staging server could use "Biotopia Staging Server".

When using a staging server on a restored snapshot of the production database, by default it will pick up the same GUID as the production server from that database. This can cause some confusion for LabKey developers when they are researching exception reports and trying to determine fixes for these problems. Changing the Server GUID for the staging server helps LabKey quickly track down exceptions and fix bugs detected on your staging server.

How-to. This change is made in the LabKey Server configuration file for your staging server. This file will be named either labkey.xml or ROOT.xml and is located in the configuration directory of your Tomcat installation.

• On Windows, this file is located in: <CATALINA_HOME>\conf\Catalina\localhost

• On OSX, this file is located in: <CATALINA_HOME>/conf/Catalina/localhost

To make the change:

1. Open the configuration file
2. Find this line in the file:

   <Loader loaderClass="org.labkey.bootstrap.LabkeyServerBootstrapClassLoader"
      useSystemClassLoaderAsParent="false" />

3. Add the following text below the line found in step 2, replacing "Server Name" with the name of your staging server:

   <!-- Set new serverGUID --> <Parameter name="org.labkey.mothership.serverGUID" value="Server Name"/>

4. Save the file
5. Restart the LabKey Server.

Change the Site Settings

Change the Site Settings Manually

1. Log on to your staging server as a Site Admin.
2. Select (Admin) > Site > Admin Console.
3. Under Configuration, click Site Settings.
4. Change the following:

• (Recommended): Base server url: change this to the URL for your staging server.
• Optional Settings to change
• Configure Security > Require SSL connections: If you want to allow non-SSL connections to your staging server, uncheck this box
• Configure Security > SSL port number: If your SSL port number has changed. By default Tomcat will run SSL connection on 8443 instead of 443. Change this value if you staging server is using a different port.
• Configure pipeline Settings > Pipeline tools: If your staging server is installed in a different location than your production server, change this to the correct location for staging.

Change the Site Settings via SQL Statements

These commands can be run via psql or pg_admin.

To change the Base Server URL run the following, replacing "http://testserver.test.com" with the URL of your staging server:

UPDATE prop.Properties p SET Value = 'http://testserver.test.com'
  WHERE (SELECT s.Category FROM prop.PropertySets s WHERE s.Set = p.Set) = 'SiteConfig'
  AND p.Name = 'baseServerURL';

To change the Pipeline Tools directory run the following, replacing "/path/to/labkey/bin" with the new path to the Pipeline tools directory:

UPDATE prop.Properties p SET Value = '/path/to/labkey/bin'
  WHERE p.Name = 'pipelineToolsDirectory';

To change the SSL Port number run this, replacing "8443" with the SSL port configured for your staging server:

UPDATE prop.Properties p SET Value = '8443'
  WHERE (SELECT s.Category FROM prop.PropertySets s WHERE s.Set = p.Set) = 'SiteConfig'
  AND p.Name = 'sslPort';

To disable the SSL Required setting:

UPDATE prop.Properties p SET Value = FALSE
  WHERE (SELECT s.Category FROM prop.PropertySets s WHERE s.Set = p.Set) = 'SiteConfig'
  AND p.Name = 'sslRequired';

Change the Look and Feel

Change the Look and Feel Manually

1. Logon to your staging server as a Site Admin.
2. Select (Admin) > Site > Admin Console.
3. Under Configuration, click Look and Feel Settings.
4. Change the following:

• System description: Add a prefix, such as the word "TEST" or "Staging" to the text in this field
• Header short name: This is the name shown in the header of every page. Again, prepending "TEST" to the existing name or changing the name entirely will indicate it is the staging server.
• Theme: Use the drop-down to change this to a different theme.

Change the Site Settings via SQL statements

These commands can be run via psql or pg_admin

To change the Header short name for the Site and for all Projects, run this, replacing "LabKey Staging Server" with the short name for your staging server.

UPDATE prop.Properties p SET Value = 'LabKey Staging Server'
  WHERE (SELECT s.Category FROM prop.PropertySets s WHERE s.Set = p.Set) = 'LookAndFeel'
  AND p.Name = 'systemShortName';

To change the System description for the Site and for all Projects, run this, replacing "LabKey Staging Server" with the system description for your own staging server:

UPDATE prop.Properties p SET Value = 'LabKey Staging Server'
  WHERE (SELECT s.Category FROM prop.PropertySets s WHERE s.Set = p.Set) = 'LookAndFeel'
  AND p.Name = 'systemDescription';

To change the Web Theme, or color scheme, for the Site and for all Projects, run this, replacing "Harvest" with the name of the theme you would like to use on your staging server.

UPDATE prop.Properties p SET Value = 'Harvest'
   WHERE (SELECT s.Category FROM prop.PropertySets s WHERE s.Set = p.Set) = 'LookAndFeel'
  AND p.Name = 'themeName';

Other settings (For Advanced Users)

Below are some additional configuration settings that you may find useful.

Deactivate all non-Site Admin users

This is important to do as it will not allow one of your researchers to accidentally log into the Staging Server.

update core.Principals SET Active = FALSE WHERE type = 'u' AND UserId NOT IN
  (select p.UserId from core.Principals p inner join core.Members m
  on (p.UserId = m.UserId and m.GroupId=-1));

Mark all non-complete Pipeline Jobs to COMPLETE

This will ensure that any Pipeline Jobs that were scheduled to be run at the time of the Production server backup do not now run on the staging server. This is highly recommended if you are using MS2, Microarray or Flow.

UPDATE pipeline.statusfiles SET status = 'ERROR' WHERE status != 'COMPLETE' AND status != 'ERROR';

Change the Site Wide File Root

Only use this if the Site File Root is different on your staging server from your production server

UPDATE prop.Properties p SET Value = '/labkey/labkey/files'
  WHERE (SELECT s.Category FROM prop.PropertySets s WHERE s.Set = p.Set) = 'SiteConfig'
  AND p.Name = 'webRoot';

Have the Staging Server start up in Admin Only mode

UPDATE prop.Properties p SET Value = TRUE
  WHERE (SELECT s.Category FROM prop.PropertySets s WHERE s.Set = p.Set) = 'SiteConfig'
  AND p.Name = 'adminOnlyMode';

Related Topics

• [adminServer