If you are the site admin and need to take down your LabKey Server for maintainence or due to a serious database problem, you can configure a "Site Down" banner message to notify users who try to access the site. Users will see a message you can configure with information about the duration of the outage or next steps.
Enable a Site Down Message
To post a "Site Down" message, the simplest method is to follow these steps:
1. Shut down Tomcat, which will shut down all current active connections, including database connections.
2. Rename your labkey.xml (or ROOT.xml) file under <catalina-home>/conf/Catalina/localhost to labkey.old (or ROOT.old).
- This will stop Tomcat from finding the LabKey web application upon startup.
3. Go to <catalina-home>/webapps/ROOT and create an HTML file with the desired maintenance message inside it.
- If your domain is the only thing hosting LabKey and nothing else, the name "index.html" is recommended since this will ensure that even going to the main domain default page will display your site down message (instead of a 404 error).
- The contents can be as simple as:
<p>LabKey is currently down while we upgrade to the latest version. </p>
4. In the <catalina-home>/conf directory, locate and edit the web.xml file, adding the following XML to it:
5. Restart Tomcat.
Now you will see the following behavior:
- The main domain URL's default index.html page will display the Site Down message you created.
- If anyone tries to access any page in that domain, even a previously valid full LabKey URL, they will also see the same site-down messsage.
- LabKey itself will not be running (since the labkey.xml or ROOT.xml file was renamed to an extension that isn't valid for xml.
Perform the necessary work that caused the need to post the site down message.
Remove the Site Down Message
When you are ready to restore the operational server, follow these steps in this order:
- Stop Tomcat.
- Remove the error-page lines you entered in the web.xml file in Step 4 above.
- Remove the HTML file you created in Step 3 above. (Move it to a location outside the <catalina-home> directory structure if you want to use the same message next time.)
- Restore the original name of the labkey.old or ROOT.old file in <catalina-home>/conf/localhost (to labkey.xml or ROOT.xml).
- Restart Tomcat.
Your server will now be back online as before the outage.
Another way to accomplish a similar goal is with the SiteDownServlet described in this section.
To enable the site down servlet, follow these steps:
- In the <labkey-home>/labkeywebapp/WEB-INF directory, locate and edit the web.xml file.
- Locate the <servlet-mapping> entry for the site down servlet, as shown below. To find it, search for the file for the string "SiteDownServlet".
- Remove the comments around the <servlet-mapping> entry to activate the site down servlet.
- Modify the message displayed to users if you wish.
- Restart Tomcat.
The relevant entries in the web.xml file appear as follows:
LabKey is currently down while we work on the server.
We will send email once the server is back up and available.
<!-- To display a nice error message in the case of a database error,
remove the comments around this servlet-mapping
and edit the message in in the init-param above.