openBIS on Ubuntu 24.04 on Azure User Guide

Overview

openBIS (open Biology Information System) is an open-source platform from Scientific IT Services at ETH Zurich for managing scientific research data across the whole experimental lifecycle. Researchers register and organise samples, experiments and the datasets they produce, annotate them with structured metadata, link related entities, and share them with collaborators under fine-grained access control. The cloudimg image installs openBIS 20.10.12.5 from the official ETH Zurich console installer with the ELN-LIMS electronic lab notebook and laboratory information management interface enabled, runs the Application Server and Data Store Server as systemd services behind an nginx reverse proxy, stores the whole installation on a dedicated Azure data disk, and generates a unique administrator password on the first boot of every VM. Backed by 24/7 cloudimg support.

What is included:

• openBIS 20.10.12.5 with the ELN-LIMS lab notebook and inventory manager, served over HTTP on port 80 by nginx
• The openBIS Application Server (AS) and Data Store Server (DSS), each running as an enabled systemd unit as the unprivileged openbis user
• PostgreSQL 15 (the version openBIS 20.10.x requires) bound to localhost, carrying the openBIS database
• OpenJDK 11, the Java runtime openBIS 20.10.x requires
• A dedicated Azure data disk at /home/openbis holding the openBIS install tree and the dataset store
• A unique administrator password generated on first boot and written to a root-only file
• ufw default-deny inbound with only ports 22 and 80 open
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet plus subnet in the target region. Standard_B2ms (2 vCPU / 8 GiB RAM) is the recommended size: openBIS runs two JVMs (the Application Server and the Data Store Server) alongside PostgreSQL, and 8 GiB keeps the stack healthy. NSG inbound: allow 22/tcp from your management network and 80/tcp for the openBIS web interface.

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for openBIS by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size; under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22) and HTTP (80). Review the dedicated data disk on the Disks tab, then Review + create -> Create.

Step 2 - Deploy from the Azure CLI

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

az vm open-port --resource-group <your-rg> --name openbis --port 80 --priority 1010

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 - Confirm openBIS is running

On first boot the appliance generates a unique administrator password, rotates the openBIS admin account to it, starts the Application Server and Data Store Server, and writes the credentials to a root-only file. The application services do not start until first boot has finished rotating the password, so the vendor default is never served.

systemctl is-active postgresql openbis-as openbis-dss nginx

All four should report active.

Step 5 - Retrieve the per-VM administrator password

The unique password generated on first boot is stored in a root-only file:

sudo cat /root/openbis-credentials.txt

You will see the login URL, the user name admin, and the generated OPENBIS_ADMIN_PASSWORD. Store this password in your password manager; it is unique to this VM.

Step 6 - Sign in to openBIS ELN-LIMS

Browse to http://<vm-public-ip>/ — you are redirected to the ELN-LIMS login page. Sign in as admin with the password from Step 5.

After signing in, the Lab Notebook opens. From here you create Spaces, Projects, Collections and Objects to structure your experiments and data.

Step 7 - Organise samples and data in the Inventory

The Inventory tab is where you manage reusable entities — Materials, Methods, Publications — and stock, keeping a shared, searchable catalogue for the whole lab.

The Tools tab gives administrators the User Manager, Vocabulary Browser, Storage Manager, exports and settings.

Architecture

openBIS is a two-server application. The Application Server (AS) serves the ELN-LIMS web interface and the V3 programmatic API on an internal HTTPS port (8443), reached by customers through the nginx reverse proxy on port 80. The Data Store Server (DSS) manages the dataset store and registers itself with the AS on start (internal port 8444). Both run as the unprivileged openbis user and store their state under the dedicated data disk mounted at /home/openbis (the install tree) with the dataset store at /home/openbis/data. PostgreSQL 15 holds the openBIS database and is bound to localhost. The firewall (ufw) denies all inbound traffic except ports 22 and 80, so the AS, DSS and database are never reachable off-box.

Step 8 - Use the programmatic API

openBIS exposes a JSON-RPC V3 API through the same nginx proxy, so you can automate registration and integrate instruments and pipelines. For example, run this on the VM (or replace 127.0.0.1 with your VM's public address when calling remotely) to obtain a session token, substituting the administrator password from Step 5:

curl -s -H 'Content-Type: application/json' \
  -d '{"id":"1","jsonrpc":"2.0","method":"login","params":["admin","<OPENBIS_ADMIN_PASSWORD>"]}' \
  http://127.0.0.1/openbis/openbis/rmi-application-server-v3.json

The response contains a result session token. The Python pybis library and the openBIS documentation describe the full API surface.

Maintenance

• Start/stop the servers: sudo systemctl restart openbis-as openbis-dss
• Logs: the AS log is under /home/openbis/openbis/servers/openBIS-server/jetty/logs/, the DSS log under /home/openbis/openbis/servers/datastore_server/log/
• Database: PostgreSQL 15 runs locally; back up the openbis_prod database with pg_dump on a schedule
• Security updates: unattended-upgrades is enabled, so OS security patches are applied automatically
• TLS: for production, front the appliance with your own TLS termination (for example an Azure Application Gateway or a customer-managed nginx certificate) so browser traffic to port 80 is encrypted in transit

Support

openBIS is developed by Scientific IT Services at ETH Zurich and is licensed under the Apache License 2.0. This cloudimg image is backed by 24/7 support. For help with the image, contact cloudimg support; for questions about using openBIS itself, see the openBIS documentation.