A number of the larger labs and institutions which run a LabKey Server, utilize a staging or test server. Test servers are used for many different reasons, such as, ensuring that a upgrade of the LabKey Server does not break any customization or to test new modules, views or queries being developed by their developers.

We have found that when using a Staging or Test server, changing the color scheme(Web Theme), server name and other look and feel settings makes it much easier for users and/or administrators to know that they are working on the test server and not the Production server. This lowers the chances that a mistake will be made which might result in data loss on the Production server (i.e., the server that is used on a day to day basis for their research).

Changes to the Test server’s settings can easily be made through the LabKey Server’s Admin Console. In addition, they can be made programmatically via the LabKey Server’s database.

Below, is our recommended list of server settings that should be changed to when using test/staging server.

Caveats

Of course there are a few caveats:

1. The SQL statements found below are only for PostgreSQL databases. The MSSQL statements are similar, but not identical. The MSSQL statements will be added a later date.
2. If you use the SQL statements to make these changes. Make the changes after you restore the Production database on the Test server and before you have started the LabKey Server.
3. This does not cover all possible changes, but just a subset of the most useful. I leave it up to the reader to create their own list of settings that should be changed on the test server.

Change the Server GUID

Summary. You can override the Server GUID stored in the database with the one specified in the LabKey XML configuration file (labkey.xml).  This ensures that the exception reports received by LabKey developers are accurately attributed to the server (staging vs. production) that produced the errors, allowing swift delivery of fixes.

Background. By default, LabKey Servers periodically communicate back to LabKey developers whenever the server has experienced an exception.   LabKey rolls up this data and groups it by GUID of each server.  When using Test or Staging servers like you are now, the Test/Staging server will have the same GUID as the Production server (because you are restoring the Production servers database periodically to your Test/Staging servers).  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 test server. This file is located in the configuration directory of your Tomcat installation.

• On Windows, the directory where this file is located is %CATALINA_HOME%\conf\Catalina\localhost
• On Solaris or MacOSX, the directory where this file is located is $CATALINA_HOME/conf/Catalina/localhost

The configuration file will be named either labkey.xml or ROOT.xml

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 line found in step 2

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

   • Replace HOSTNAME with the name of your test server
4. Save the file
5. Restart the LabKey Server.

Change the Site Settings

 
Change the Site Settings manually

1. Logon to your test server as a Site Admin
2. In the upper right hand corner of the page, select Admin -> Site -> Admin Console.
3. On the Admin Console page, click Site Settings.
4. On the Site Settings page, change the following settings
   • [Recommended]: Base server url: change this to URL for your test server.
   • Optional Settings to change
     • Pipeline tools directory:
       • If your test server is installed in a directory location than your Production server, change this to proper location.
     • Require SSL connections:
       • If you want to allow non-SSL connections to your test server, uncheck this box
     • 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 test server is using a different port.

 
Change the Site Settings via SQL statements These commands can be run via psql or pg_admin

To change the Base Server URL run

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'; 
 -- Replace `http://testserver.test.com` with the URL or your test server 

 
To change the Pipeline Tools directory run

UPDATE prop.Properties p SET Value = '/path/to/labkey/bin' 
 WHERE p.Name = 'pipelineToolsDirectory'; 
 -- Replace the `/path/to/labkey/bin` with the new path to the Pipeline tools directory 

 
To change the SSL Port number:

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'; 
 -- Replace the `8443` with the SSL port configured for your Test Server 

 
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 Test server as a Site Admin
2. In the upper right hand corner of the page, select Admin -> Site -> Admin Console.
3. On the Admin Console page, click Look and Feel Settings.
4. On the Look and Feel Settings page, change the following settings
   • System description: Recommend pre-pending the word [TEST] or something similar the text in this field
   • Header short name: This is the name shown in the header of every page. I recommending appending [TEST] to the existing name or changing the name entirely to indicate it is the Test server
   • Web Theme: Using the drop-down change this to a different theme name

NOTE: Following these instructions will change the Site Look and Feel settings. If you have customized the Look and Feel on an individual project(s), you will need to go to the Look and Feel settings for each Project and make a similar change,

 
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:

UPDATE prop.Properties p SET Value = 'LabKey Test Server' 
 WHERE (SELECT s.Category FROM prop.PropertySets s WHERE s.Set = p.Set) = 'LookAndFeel' 
 AND p.Name = 'systemShortName'; 
 -- Replace "LabKey Test Server" with the short name for your Test server. 

 
To change the System description for the Site and for all Projects

UPDATE prop.Properties p SET Value = 'Test LabKey Server' 
 WHERE (SELECT s.Category FROM prop.PropertySets s WHERE s.Set = p.Set) = 'LookAndFeel' 
 AND p.Name = 'systemDescription'; 
 -- Replace "Test LabKey Server" with the system description for your Test server 

 
To change the Web Theme for the Site and for all Projects:

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'; 
 -- Replace "Harvest" with the name of the Web Theme you would like to use on your Test Server. 

Other settings [For Advanced Users]

Below are some additional configuration settings that we have found useful in working with our larger customers. Below is only the SQL statements for making these changes, so of these changes can only be reasonably be done via these SQL statements.

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 Test 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 Test server. If you are using MS2, MS1, GenMicroarray or Flow I highly recommend this.

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 Test 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 Test server startup 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';