LabKey Server 26.7 Community Edition on Ubuntu 24.04 on Azure User Guide

Overview

LabKey Server is an open-source scientific data management platform used by biomedical and translational research groups to organise study data, assay results and sample information behind a single secure web interface. It gives a team projects and folders with fine-grained permissions, typed datasets and lists, a schema and query browser with its own SQL dialect, charts and reports, a wiki and an issue tracker - so research data lives in a queryable system of record rather than scattered spreadsheets.

The cloudimg image installs LabKey Server 26.7.0 Community Edition as a self-contained appliance. The Community Edition distribution is a single Spring Boot application with Apache Tomcat 11 embedded, so there is no separate servlet container to install or patch. It runs on Eclipse Temurin 25 (the only Java version LabKey supports) as a dedicated unprivileged labkey service account bound to the loopback interface, with nginx in front on port 80. PostgreSQL 16 is bundled on the same VM as the application database. Every VM generates its own administrator password, database password and encryption key on first boot, and the image ships with a small preloaded demo study so the platform shows real content the moment it comes up. Backed by 24/7 cloudimg support.

What is included:

• LabKey Server 26.7.0 Community Edition (Apache-2.0) with Apache Tomcat 11.0 embedded
• Eclipse Temurin 25 JDK (LTS) - the only Java version LabKey supports
• PostgreSQL 16 bundled locally as the LabKey application database, tuned for a single-node appliance
• nginx on :80 reverse-proxying the loopback LabKey connector on 127.0.0.1:8080
• A per-VM site administrator account, PostgreSQL password and encryption key generated on first boot and recorded in a root-only file
• A preloaded Demo Biomarker Study - a date-based study with a 600-row BiomarkerResults dataset across 60 participants and 12 time points, plus a 600-row SampleMeasurements list
• The full Community Edition module set: studies, assays, experiments, lists, queries, visualisations, file content, search, wiki, issue tracker and the audit log
• labkey_server.service, nginx.service and postgresql.service as systemd units, enabled and active
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet + subnet in the target region.

Sizing: use Standard_B2ms (2 vCPU / 8 GiB RAM) or larger. This matches LabKey's own published guidance, which specifies 8 GB as the minimum and 16 GB as the recommended memory for a small single-machine installation. The image ships a JVM heap of -Xms512m -Xmx2G, which leaves ample room on an 8 GiB VM.

NSG inbound: allow 22/tcp from your management network and 80/tcp from the clients that need the web interface. LabKey serves plain HTTP on port 80 in this image; for production, terminate TLS in front of it with your own domain and certificate.

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for LabKey Server by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size (Standard_B2ms or larger); under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22) and HTTP (80). Then Review + create -> Create.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name labkey \
  --image <marketplace-image-urn> \
  --size Standard_B2ms \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_rsa.pub \
  --public-ip-sku Standard

Open the ports you need:

az vm open-port --resource-group <your-rg> --name labkey --port 80 --priority 1001

Step 3 - Wait for first boot to finish

The first boot does real work: it mints this VM's secrets, creates the LabKey application database, runs the initial schema bootstrap across all modules, creates the site administrator account and loads the demo study. This takes roughly one to two minutes after the VM reports running. Until it completes, the web interface may briefly answer with a "server is not ready" message - that is the module bootstrap finishing, not an error.

Check progress over SSH:

sudo systemctl is-active labkey-server-firstboot.service

When the unit reports active (exited), first boot is done.

Step 4 - Retrieve the per-VM administrator password

Every VM generates its own credentials. They are written to a root-only file:

sudo cat /root/labkey-credentials.txt

This gives you the site administrator email (admin@cloudimg.local), the generated administrator password, and the generated PostgreSQL role password. Nothing in this image ships with a shared or default password - the values are unique to your VM and are created the first time it boots.

Sign in at http://<vm-public-ip>/.

Change the administrator password after your first sign-in, from the user menu in the top right.

Note on failed sign-ins. LabKey blocks a client host after several failed sign-in attempts, and while that block is active it will reject the correct password too. If you lock yourself out, wait rather than continuing to guess.

Step 5 - Explore the preloaded demo study

The image ships with a Demo Biomarker Study so you can see the platform working before loading any of your own data. Open it from the project menu in the top left.

The study overview reports what it holds - one dataset, twelve time points and sixty participants - and the tabs across the top give you the Participants view and the Clinical and Assay Data browser.

Open Clinical and Assay Data -> BiomarkerResults to see the dataset itself: 600 assay results keyed by participant and date.

From this grid you can sort, filter, chart, and export the data, or use Manage to change the dataset definition. The demo study is ordinary content - delete it once you have your own data loaded.

Step 6 - Browse the schema and query your data

The Query Schema Browser (gear menu -> Go To Module -> Query, or /Demo%20Study/query-begin.view) lists every schema the Community Edition exposes.

study holds subjects, visits and datasets; lists holds each defined list; exp covers experiment runs, data files and sample types; assay covers assay designs and runs; and auditLog records who changed what. You can write LabKey SQL against any of them and save the result as a named query.

Step 7 - Load your own data

Create a project of your own from the project menu (New Project), pick a folder type - Study for participant/time-based research data, Collaboration for a general workspace - and then either:

• Create a study dataset: in a Study folder, use Manage -> Manage Datasets -> Create New Dataset, define your fields, then import rows from a TSV or Excel paste.
• Create a list: gear menu -> Manage Lists -> Create New List for reference data that is not participant/time keyed.
• Import a spreadsheet: most grids accept Import Data with a copy-paste or file upload, mapping columns to fields.

The demo study's BiomarkerResults dataset is a working example of the first pattern - a date-based dataset with participant, date, assay type, result and units.

Maintenance

Service control. The appliance is three systemd units:

sudo systemctl is-active labkey_server nginx postgresql

LabKey logs go to the journal: sudo journalctl -u labkey_server -f.

Memory. The JVM is configured with -Xms512m -Xmx2G in /etc/systemd/system/labkey_server.service. The maximum heap must stay at 2 GB or above - below that LabKey displays a persistent "heap memory is too low" warning on every page. If you size the VM up and want a larger heap, raise -Xmx and restart labkey_server.

Database. PostgreSQL 16 runs locally with the LabKey database named labkey, owned by the labkey role. Back it up with pg_dump:

sudo install -d -m 0700 /var/backups
sudo -u postgres pg_dump labkey | gzip > /tmp/labkey-backup-test.sql.gz && ls -la /tmp/labkey-backup-test.sql.gz

The application also holds an encryption key in /labkey/labkey/config/application.properties which protects secrets stored in the database - back that file up alongside your database dump, because a restore without the matching key cannot decrypt those values.

Operating system updates. The image ships fully patched with unattended-upgrades enabled, so security updates continue to apply on your VM as normal.

Usage reporting. LabKey can report usage statistics back to LabKey Corporation, which includes environment details and the site administrator's email address and organisation name. This image sets reporting to the minimum level on first boot. You can review or change it under the gear menu -> Site -> Admin Console -> Settings -> Usage/Exception Reporting.

Editions

This image ships LabKey Server Community Edition, which is free to download and use, licensed under the Apache License 2.0, and carries the full core data-management module set described above. LabKey Corporation also sells Premium Editions that add features not present in the Community Edition - specialty assays, electronic lab notebook, sample management, LDAP/SSO/multi-factor authentication, compliance tooling and vendor support. Those are not included in this image, and LabKey's own in-product link about them is visible in the interface.

Support

Backed by 24/7 cloudimg support. This image is produced by cloudimg and is not affiliated with, endorsed by, or supported by LabKey Corporation. "LabKey" is a trademark of LabKey Corporation, used here only to identify the software this image contains.