Module Development
During
development, you will typically want to keep your module uncompressed so that you can quickly add or adjust those resources that can be automatically reloaded. Any changes you make to queries, reports, HTML views and web parts will automatically be noticed and the contents of those files will be reloaded without needing to restart the server.
Typically you will develop a module on a developer machine, then deploy it to a
staging server when it's working so that you can fully test it in a realistic context.
Move to Production
Once you are satisfied that your module is finished, you will move it from the
staging server to the
production server. Moving the module can be done either by copying the uncompressed module directory and its subdirectories and files from the staging server to the production server, or by compressing the module directory into a .module file and copying that to the production server. Which technique you choose will probably depend on what kind of file system access you have between the servers. If the production server's drive is mounted on the test server, a simple directory copy would be sufficient. If FTP is the only access between the test and production servers, sending a compressed file would be easier.
An easy way to
compress the module directory is to use the JAR utility, which can also be automated via a Gradle build task. Use the standard JAR options and name the target file "<module-name>.module".
Deploy the Module
Deploy the .module file using the
server UI or by copying it to the <LABKEY_HOME>/externalModules/ directory on your production server. This location is parallel to the <LABKEY_HOME>/modules directory which contains the modules you obtain with your distribution. You may have to create the externalModules directory.
Do not add any of your own modules directly to the "modules" location. While it may work in some cases, when you upgrade, your user-provided code will be overwritten. Use the "externalModules" location for anything not provided to you by LabKey.
A server running in production mode will not recognize a new module; a manual server restart is required. A production server will monitor existing modules for changes. When it loads the module, it will automatically expand the .module into a directory with the same base name (overwriting the existing directory and files), and load the newly-updated module's resources. Note that generally a module must also
be enabled in the folder to be usable there.
- Shut down the server.
- Create the "<LABKEY_HOME>/externalModules" directory in your LabKey installation if it does not exist already.
- Copy the .module file to that new directory.
- Start LabKey.
Update the Module
Most files in a module can be
updated while the production server is running (sql queries, html views, trigger scripts, assay domains and views) without restarting. Some files cannot be updated while the server is running (SQL scripts, assay provider definitions, compiled Java code, etc.) and require a manual restart of the server.
Related Topics
Premium Features AvailableSubscribers to the Professional or Enterprise Edition of LabKey Server can load modules on production servers without starting and stopping them, and on development machines, can edit module resources from within the user interface. Learn more in these topics:
Learn more about premium editions