UniteLabs Desktop

UniteLabs Desktop is a self-contained, Docker-based distribution of the UniteLabs Platform for a single machine on your premises. The bundle ships with all Docker images included: the API, frontend, Web IDE, workflow engine, as well as secrets, SQL, S3-compatible storage and all Python SDK dependencies. The platform itself installs and runs without access to the UniteLabs registry or other external sources. Connectors are delivered separately: GroundControl downloads them when the connector host has internet access. In restricted environments you upload the connector executable as a file instead.

Use it for:

• Largely offline or airgapped environments
• IT restrictions that do not allow connections to external domains (for example unitelabs.io or gitlab.com)
• Data-residency-restricted deployments
• Trials and evaluations on a single workstation

For cloud tenants, no installation is needed; see Connect to Platform. For private cloud deployments, we coordinate the setup with your IT team.

Prerequisites

• A Linux host (Ubuntu 22.04 or newer recommended). Linux is the tested and supported target; if you need to run on a Windows or macOS host, talk to your UniteLabs contact first.
• Docker CE with the Compose plugin (Docker Engine 27 or newer), installed from the official Docker repository following the official Docker install guide for Ubuntu. Distribution packages such as Ubuntu's docker.io package or the Docker snap ship an outdated Compose that breaks the installer.
• The installing user must be in the docker group. Group membership takes effect after logging out and back in.
• make and mkcert must be installed via your package manager. For browsers to trust the local certificate, libnss3-tools (certutil) must be present as well. On Ubuntu: sudo apt install make mkcert libnss3-tools.
• If other machines on the network need to reach the platform: clients address the platform by hostname, not by IP, so the platform hostname must resolve to the host's IP from every client machine. That works either through an internal DNS record or through hosts-file entries on the clients. With hosts-file entries the host needs a static IP (or a DHCP reservation), because the entries hardcode the IP.
• The UniteLabs Desktop bundle (a single .tar.gz); contact your UniteLabs representative for access.

Install

The bundle's INSTALL.md and PREREQUISITES.md contain the exact commands for that bundle version. The generic flow is:

1. Copy the bundle onto the target machine and unpack it. This creates a dist/ folder with a Makefile, docker-compose.yaml, environment files, the bundled images archive, and the install docs.
2. Create the local certificates: make setup-certificates (uses mkcert to create a local CA and a certificate for the platform hostname).
3. Load the bundled images into Docker as described in INSTALL.md.
4. Initialize the stack: make init (runs database migrations and creates the object storage bucket for your tenant).
5. Add the platform hostnames to /etc/hosts, mapping the platform host and the API host to localhost. The hostnames are pre-configured per deployment and named in INSTALL.md; the entry looks like 127.0.0.1 unitelabs.platform api.unitelabs.platform.
6. Start the stack: make up and wait until all containers report Healthy or Started.

Then open the platform hostname in a browser on the machine, for example https://unitelabs.platform. The hostname is pre-configured for your deployment and named in the bundle's INSTALL.md (it is the same name you added to the hosts file in step 5). The default admin credentials are handed over by your UniteLabs representative together with the bundle; log in with them and change the password on first login.

Verify the installation

• docker compose ps in the dist/ folder shows all containers as Healthy or Started.
• The API answers: curl https://unitelabs.platform/v1/health returns HTTP 200. Replace unitelabs.platform with your platform hostname; the API is served under the platform hostname at /v1.
• The platform login page loads in the browser and login works.
• The Web IDE opens from the platform navigation: create a notebook and run this cell:

  import os, urllib.request
  
  print(urllib.request.urlopen(os.environ["BASE_URL"] + "/health").status)
  

  
  It prints 200. The notebook gets the platform URL and the certificate trust from the installation, so this also shows that code in the Web IDE reaches the API.
• The workflow engine runs a workflow: open the Workflows page in the platform and trigger a run. A fresh install has no workflows deployed yet; set up the SDK first (next section) and deploy the hello_world workflow from the workflow template. A successful run reaches the state COMPLETED and logs the SDK version.
• If other machines on the network need access, for example a GroundControl host connected to an instrument: the platform URL loads on those machines as well. This requires the name resolution from the prerequisites (DNS record or hosts-file entry on the client).

Connect with the Python SDK

To control the platform from your own code, install the SDK as described in SDK installation. The SDK client reads BASE_URL, AUTH_URL, CLIENT_ID and CLIENT_SECRET from the environment or an .env file. For UniteLabs Desktop these values are deployment-specific; your UniteLabs representative hands them over together with the bundle. The workflow template contains ready-made scripts to test the connection, for example scripts/get-all-workflows-from-api.py, which authenticates with your .env and lists the workflows on the platform.

Connect an instrument

Install GroundControl on the machine connected to your instrument and register the connector against the platform URL of your UniteLabs Desktop installation. See GroundControl. When the connector host has internet access, GroundControl downloads connectors directly. In restricted environments, get the GroundControl installer and the connector executable as files from your UniteLabs representative and use GroundControl's Upload Connector option instead.

Troubleshooting

• docker: command not found or make init fails on an env-file flag: the distribution Docker package is installed or Docker is missing. Remove distro packages and install Docker CE with the Compose plugin from the official repository.
• Permission denied on the Docker socket: the user is not in the docker group yet, or the group change has not taken effect. Add the user and log out and back in.
• Browser shows 404 although all containers are healthy: check the hosts-file entry for the platform hostname, and check for remnants of previous deployments. An old router or ingress (for example from an earlier k3s install) can intercept requests and answer 404 while the new stack is healthy. Take an inventory and stop old components before installing.
• Browser shows "Not secure": the mkcert CA is not trusted. Install libnss3-tools and rerun the mkcert install step.
• make up fails after an interrupted first run: run make up again.

Limitations and notes

• All Python packages must be baked into the bundle upfront; there are no dynamic library downloads at run time.
• Component versions are pinned per bundle in its versions.env. Updates ship as a new bundle.