As of Wednesday, April 13th 2011, this message board will no longer be updated. LabKey now has a blog (see http://www.labkey.com/blog/) and in the future all Administration/Operations related postings will be made there.

If you are only interested in the Administration/Operations related postings, you can simply filter the entries and look only at thoise in the Operations category. Here is a direct link.

Please note: some of the content from this message board has been moved to the new blog location.

Overview

Sample Script: upgrade-windows-manual.bat

This sample script is used internally for upgrading a LabKey Server that was manually installed on Windows. On Windows, there are two methods to install the LabKey Server. The first is to use the configWindows. The second is perform a manualInstall This script can be used when upgrading a LabKey Server on Windows which was installed manually only. This script should never be used to upgrade a LabKey Server that was installed using the configWindows.

This is a very simple script, but with a little customization, as described below, you should be able to quickly start using it for your LabKey Server installation.

How to customize the script

Nearly all script customization can be done by changing the variables at the beginning of the script. Below is a description of each variable.

• labkey_home: This is the installation directory for the LabKey Server. This directory contains the labkeywebapp and modules directory among others. For many customers this is set to /usr/local/labkey
• labkey_distdir: This is the directory which will hold the uncompressed LabKey distribution directories. For example:
• If you downloaded the current LabKey distribution (LabKeyxx.x-xxxxx-xx-bin.zip, where "xx.x-xxxxx-xx" represents the current version number) into h:\labkey\dist
• Then uncompressed the distribution file into h:\labkey\dist\LabKeyxx.x-xxxxx-xx-bin using a command similar to

cd h:\labkey\dist and 
unzip LabKeyxx.x-xxxxx-xx-bin.zip

• Then the labkey_distdir should be set to h:labkeydist
• catalina_home: This is the installation directory for the Tomcat Server

• Tomcat Windows Service: This script assumes that the Tomcat Windows service is called *Apache Tomcat*. If the Tomcat Windows service on your server is named something different, please make the change in the script.

How to use this script

upgrade-windows-manual.bat DIST

upgrade-windows-manual.bat LabKeyxx.x-xxxxx-xx-bin

Additional Notes

Roll back to previous version:

• This script does not keep a backup copy of the LabKey Server java files before the upgrade. In order to install a previous version, you will need to have the LabKey Distribution files available on your file system.
• You can then simply execute the script again specifying the previous versions directory containing the uncompressed LabKey Server distribution files

• This script does not perform a backup of your LabKey Server database.
• LabKey recommends that you perform a backup of your LabKey Server database before upgrading your LabKey Server using this script.
• See dbBackup and backupScenarios for more information on backing up your database.

• Linux Upgrade Script
• Control how internet search engines (google) index your LabKey Server

Information on the Postgres Backup implementation

There are 3 output formats for a backup of a postgres database. I am going to describe the pros and cons of each below

Script or plain-text format

• This is the default format for backup
• This is simply a text file which contains the commands necessary to rebuild the database.
• Can be restored using psql or pgrestore
  • As of Postgres 8.2, you can backup “large objects” using this format by specifying the -b option. (See section titled E.57.3.12. pgdump Changes in http://www.postgresql.org/docs/8.4/static/release-8-1.html)
• Individual tables CANNOT be restored using the format. In order to restore an individual table, you will need to restore the entire table first. Then copy the table contents from the restored database to the working database.

Custom archive format

• Most flexible format.
• By default this format is compressed, but compression can be disabled using the —compress option
• Must use pg_restore to restore the database
• The backup file can be opened and the contents reviewed using pg_restore
• Individual tables CAN be restored using the format.
• Backup file size(uncompressed) can be roughly 2x the size of the database. This is due overhead necessary to allow pg_restore the ability to restore individual tables, etc

tar archive format

• Has the same features as Custom format except
• Tables cannot be larger than 8GB in size or the restore will fail.
• Output file can be opened using the tar command.

(Much of this information was found at http://www.postgresql.org/docs/8.4/static/app-pgdump.html and http://www.postgresql.org/docs/8.4/static/app-pgrestore.html ]

NOTE: The content below pertains to using the LabKey Server with a PostgreSQL database only. It does not apply when using a Microsoft SQL Server.

In our install documentation we assume that the database user, being used by the LabKey server to communicate to the database, has superuser status.

If you are uncomfortable with granting the database user superuser status, then the instructions below can help you install the LabKey server using a user without the superuser status.

First, a little background about the privileges required of the database user used by LabKey Server. The database user only requires superuser status during the initial install. After the first installation, the LabKey Server only requires that the database user is the owner of the database. When the LabKey Server is started, if the database, specified in the configuration file, does not exist, then the LabKey Server will attempt to create the database. Thus the superuser status is only needed during the very first startup of the LabKey Server.

In order to run the LabKey server with a non-superuser database user I recommend the following: NOTE: These instructions assume you are using the postgres user (ie the database user created during the run of initdb, this user superuser status.)

1. Using the postgres user, create a new database role named labkey with a strong password

2. Using the postgres user, create a new database named labkey. Make sure to specify the user labkey as the owner. i.e.

   CREATE DATABASE labkey OWNER labkey;
   

3. open the labkey.xml configuration file and in the database configuration XML node:

   • enter in the labkey as the user
   • enter in password choosen in #1
   • enter in labkey as the database
4. Start the LabKey server.

The LabKey Server bootstrap process will happily install itself using the labkey database

As you know, the LabKey Server runs on Apache Tomcat. The Tomcat server has the ability to perform Access Logging similar the Apache web server. When configured, the Tomcat server will log each request to the server to a file on the file system. By default:

• the log file is located in the $CATALINA_HOME/logs directory
• the log file name will be of the form localhost_access_log.YYYY-MM-DD.txt
  • where YYYY = 4 digit year, MM = month and DD is the day of the month.
• the log file is rotated daily at midnight

The Tomcat server comes with two preconfigured Access Log formats; common and combined. If I had to choose one of these format, I would recommend the combined format. The format of the combined format is

%h %l %u %t "%r" %s %b Referer User-Agent'

See below for a description of what each pattern code (ie %h) means. Complete documentation on the Tomcat Access Logging can be found at http://tomcat.apache.org/tomcat-5.5-doc/config/valve.html

Recommended LabKey Server Access Log format

For production installations of the LabKey server, I recommend a new format:

%h %l %u %t "%r" %s %b %D %S "%{Referer}i" "%{User-Agent}i" %{LABKEY.username}s

The difference between this format and the combined format is

• %D = The time taken by the server to process the request. This is valuable when debugging performance problems
• %S = Tomcat User SESSION ID
• %{LABKEY.username}s = The username of the person accessing the LabKey server. If the person is not logged in, then this will be a “-“

There are 3 other LabKey specific fields that might be of interest in particular circumstances

• %{LABKEY.container}r = The LabKey server container being accessed during the request
• %{LABKEY.controller}r = The LabKey server controller being used during the request
• %{LABKEY.action}r = The LabKey server action being used during the request

Example Access Log Valve configuration

Below is an example configuration for using the pattern above

<Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs" prefix="localhost_access_log." 
suffix=".txt" pattern='%h %l %u %t "%r" %s %b %D %S "%{Referrer}i" "%{User-Agent}i" %{LABKEY.username}s' 
resolveHosts="false"/>

Pattern Code description

This was taken from http://tomcat.apache.org/tomcat-5.5-doc/config/valve.html

• %a - Remote IP address
• %A - Local IP address
• %b - Bytes sent, excluding HTTP headers, or ‘-’ if zero
• %B - Bytes sent, excluding HTTP headers
• %h - Remote host name (or IP address if resolveHosts is false)
• %H - Request protocol
• %l - Remote logical username from identd (always returns ‘-‘)
• %m - Request method (GET, POST, etc.)
• %p - Local port on which this request was received
• %q - Query string (prepended with a ‘?’ if it exists)
• %r - First line of the request (method and request URI)
• %s - HTTP status code of the response
• %S - User session ID
• %t - Date and time, in Common Log Format
• %u - Remote user that was authenticated (if any), else ‘-‘
• %U - Requested URL path
• %v - Local server name
• %D - Time taken to process the request, in millis
• %T - Time taken to process the request, in seconds
• %I - current request thread name (can compare later with stacktraces)

There is also support to write information from the cookie, incoming header, outgoing response headers, the Session or something else in the ServletRequest. It is modeled after the apache syntax:

• %{xxx}i for incoming request headers
• %{xxx}o for outgoing response headers
• %{xxx}c for a specific request cookie
• %{xxx}r xxx is an attribute in the ServletRequest
• %{xxx}s xxx is an attribute in the HttpSession

Below are some tips for getting better results when using LabKey’s full-text search feature. These are from one of our Search developers, Adam.

1. If your search term is a phrase then enclose it in quotes. Otherwise, you’ll get all documents that include any of the terms (though those that include more terms should appear higher in the results).
2. If your search term includes special characters, try enclosing it in quotes. Or

3. If your search term includes special characters, try escaping the special characters

   • Our search engine supports escaping special characters that are part of the query syntax. The current list special characters are

     + - && || ! ( ) { } [ ] ^ " ~ * ? : \
     

   • To escape these character use the \ before the character. For example to search for (1+1):2 use the query:

     \(1\+1\)\:2
     

4. If you’re searching our Bug Tracker, then definitely use the Bug Tracker search page at https://www.labkey.org/issues/home/Developer/issues/list.view?. This limits results to a single type and folder.

Below you will find the instructions for installing the LabKey SiteDown webapp. This webapp allows the LabKey Administrator to show a pretty SiteDown page when the LabKey server needs to be taken offline.. This SiteDown webapp is designed to be used only during certain types of outages, such as when the database server is offline due to a hardware failure, or upgrade.

This SiteDown webApp is not meant to be used in the following cases

• during LabKey Server upgrades (ie upgrade of the LabKey Server from v9.1 to v9.2)
• during times when you want to perform maintenance on the LabKey Server by placing the server in Admin-Only mode.

How does the SiteDown webapp work?

The LabKey Server currently has a very simple SiteDown functionality. When enabled, by editing the <LABKEY_HOME>/labkeywebapp/WEB-INF/web.xml file, it will show a simple message to the screen. This message contains no formatting, logo images, etc. It is just black text on the white background. I have leveraged this functionality to redirect the browser to a new webapp that allows us to show a “prettier” SiteDown page.

When enabled, the SiteDown page will work in the following way

1. When the user comes to any page within the LabKey webApp (ie http://<YourServerName>/labkey/Project/home/begin.view)
2. The LabKey webApp will return a small blurb of javascript. The javascript tells the browser to load http://<YourServerName>/sitedown/index.html
   • The URL to load is configurable and can be changed.
3. The browser then loads http://<YourServerName>/sitedown/index.html and shows the user the “prettier” SiteDown page
4. This page contains a Meta Refresh directive which tells the browser to load http://<YourServerName>/labkey/Project/home/begin.view every 60 secs.
   • This insures that if a user leaves their browser open after they see the SiteDown page, they will eventually get redirected back the LabKey webApp when it is back online.

Preparations for Using the Site Down page

1. Log in to the web server which is running your LabKey Server
2. Copy/Download the attached file, labkey_sitedown.zip, to your server.
3. Unzip the file into <LABKEY_HOME>/sitedown

Edit the Site Down page to show the desired message

1. Using an editor open <LABKEY_HOME>/sitedown/sitedown/index.html
2. Find the text “This is the message”
3. Replace this with the content you would like to have displayed. Note: this is an HTML page, you can add in any supported HTML tags you would like.

4. If your LabKey webapp is configured to use a different ContextPath than /labkey, you will need to edit the Meta Refresh tag. i.e. the tag that begins with

   <meta http-equiv="refresh" content="60;url=/labkey/index.html">
   

Enable the SiteDown webapp and test

1. Using an editor open <LABKEY_HOME>/sitedown/sitedown.xml
2. Change the docBase attribute from CHANGETHIS to <LABKEY_HOME>/sitedown/sitedown
   • where <LABKEY_HOME> is the directory where the LabKey software is installed
3. Copy <LABKEY_HOME>/sitedown/sitedown.xml to <CATALINA_HOME>/conf/Catalina/localhost/sitedown.xml
   • [NOTE the tomcat server will automatically load the new SiteDown webapp. This will allow you verify the formatting of your SiteDown page]
4. Goto http://<YourServerName>/labkey/sitedown/index.html and verify that the SiteDown message looks correct. If you need to fix any of the content or formatting, simply open <LABKEY_HOME>/sitedown/sitedown/index.html with an editor and make the changes. Once you save the file, refresh your browser to review your changes.

Redirect from the CPAS webapp to the SiteDown page

When it is time to show the “SiteDown” page, do the following

1. Make a backup of the web.xml file by copying <LABKEY_HOME>/labkeywebapp/WEB-INF/web.xml to <LABKEY_HOME>/orig_web.xml
2. Copy <LABKEY_HOME>/sitedown/sitedown_web.xml to <LABKEY_HOME>/labkeywebapp/WEB-INF/web.xml
3. Restart the Tomcat Server
4. Test by going to http://<YourServerName>/labkey/Project/home/begin.view

Bring the LabKey webapp backup online

1. Copy <LABKEY_HOME>/orig_web.xml to <LABKEY_HOME>/labkeywebapp/WEB-INF/web.xml
2. Disable the sitedown webapp by deleting <LABKEY_HOME>/sitedown/sitedown.xml
3. Restart the Tomcat Server
4. Test by going to http://<YourServerName>/labkey/Project/home/begin.view

Other Information

The SiteDown page in the attached zip archive is a sample. By editing the index.html file located in the sitedown directory, you should be able to customize the look and feel of the page to match your server.