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:
<error-page>
<location>/index.html</location>
</error-page>
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.
Proxy or Load Balancer
If you are using a proxy, load balancer, or other service that forwards HTTP requests from clients to Tomcat, they will typically have the ability to present a page when the primary server is offline. Consult the documentation for your service.
Related Topics
