DecentraLabs Lab Gateway

Lab Gateway is the access plane for DecentraLabs laboratories. It exposes browser-based remote sessions through Guacamole, coordinates optional FMU access, and connects the laboratory network to the institutional control plane. The repository also embeds the canonical blockchain-services backend for a complete deployment.

Start with the documentation guide. It is the entry point for installation, deployment modes, operational runbooks, and component-specific documentation.

Architecture at a glance

Lab Gateway separates the control plane from the access plane:

• The control plane issues credentials, performs provider administration and on-chain operations. It is an embedded Full backend or an independent blockchain-services deployment.
• The access plane is the public gateway selected by a laboratory's accessURI. It contains OpenResty, Guacamole, Ops Worker, and optional FMU services close to the laboratory network.

flowchart LR
    User[User or FMI client]
    Marketplace[Marketplace]
    Chain[(Smart contracts)]
    Control[Full Gateway backend or standalone blockchain-services]
    Edge[Full or Lite Lab Gateway]
    Guac[Guacamole]
    Ops[Ops Worker]
    Fmu[FMU Runner]
    Station[Lab Station / laboratory network]

    User --> Marketplace
    Marketplace <--> Control
    Control <--> Chain
    Marketplace --> Edge
    User --> Edge
    Edge --> Guac --> Station
    Edge --> Ops --> Station
    Edge --> Fmu --> Station
    Control -. JWT, codes, provisioning and evidence .-> Edge

Loading

ISSUER chooses the credential authority. accessURI chooses the gateway that serves the user's access. They can be different: a Full or standalone backend may authorize a session served by a Lite Gateway.

Choose the deployment shape

Shape	Credential issuer and provider control	Local access plane	ISSUER
Full	Embedded blockchain-services	This Gateway	Empty
Lite	Remote Full Gateway or standalone backend	This Gateway	Remote <origin>/auth
Full + N Lite	One Full backend	Full and N Lite Gateways	Lite instances point to Full
Standalone backend + N Lite	Independent backend	N Lite Gateways	Lite instances point to backend

Read Deployment architectures before configuring a composite deployment. It defines the required trust bundle, provisioner route, and Lab Station boundaries.

Quick start

For a first Full deployment, use the interactive setup script:

git clone --recurse-submodules https://github.com/DecentraLabsCom/Lab-Gateway.git Lab-Gateway
cd Lab-Gateway
./setup.sh                         # Linux/macOS
# setup.bat                        # Windows

For a non-interactive deployment, copy .env.example and blockchain-services/.env.example, configure the required secrets and public origin, then run:

docker compose up -d --build
docker compose ps
curl -k https://localhost/health

The setup and manual-installation guides explain the required values, wallet setup, TLS, Lite mode, and verification:

• Setup script — English / Español
• Manual Docker Compose — English / Español
• NixOS compose-managed host — English / Español

Services and optional profiles

The default stack starts openresty, blockchain-services (Full mode only), mysql, guacamole, guacd, and ops-worker. Compose profiles are opt-in:

Profile	Purpose	Typical command
fmu-runner	Production FMU facade; executes through Lab Station	FMU_RUNNER_ENABLED=true docker compose --profile fmu-runner up -d
fmu-local-dev	Isolated local FMU development/testing; never production	FMU_RUNNER_ENABLED=true FMU_LOCAL_REALTIME_ENABLED=true docker compose --profile fmu-local-dev up -d openresty fmu-runner-local
aas	Bundled BaSyx AAS and MongoDB	docker compose --profile aas up -d
certbot	ACME certificate acquisition/renewal	docker compose --profile certbot up -d
cloudflare / cloudflare-token	Cloudflare Tunnel variants	See the setup guide

Do not start both FMU profiles: they intentionally use the same internal upstream alias. For the complete configuration model, see Configuration reference.

FMU_BACKEND_MODE selects where the FMU executes and is independent of the Full/Lite authentication topology. The runner uses the local blockchain-services JWKS endpoint in Full mode and the external issuer JWKS endpoint in Lite mode; AUTH_JWKS_URL is available as an explicit override.

Security model

• Browser hand-off uses a one-time opaque access code. OpenResty redeems it server-to-server and sets a Secure, HttpOnly JTI cookie; lab JWTs do not appear in URLs.
• Administrative surfaces use short-lived, path-scoped cookies created by POST /lab-manager/login or POST /admin/login. Query-string tokens and browser-storage tokens are rejected.
• Lite mode is an access-plane mode. It does not start a second issuer or make wallet, billing, intents, or local /auth/** issuer APIs available.
• Station WinRM, Guacamole protocols, MySQL, internal FMU services, and Ops Worker endpoints must remain off the public edge.

See Laboratory connectivity and operations and health for the network and operator model.

Documentation map

• Documentation guide — task-based navigation and terminology.
• Deployment architectures — Full, Lite, composite, and standalone topologies.
• Configuration reference — environment files, required secrets, profiles, and validation.
• Operations and health — health endpoints, diagnostics, backups, and incident triage.
• First lab session — provider journey from setup to an authenticated session.
• FMI/FMU support and AAS support — digital-twin capabilities.

Repository layout

openresty/                 Public edge, access-code exchange, and access guards
blockchain-services/       Embedded canonical Spring Boot control-plane backend
ops-worker/                Private WinRM, Wake-on-LAN, telemetry, and operations worker
fmu-runner/                FMU facade and Station integration
web/                       Lab Manager and static gateway UI
docs/                      Installation, architecture, workflows, and references
tests/                     Gateway integration checks

Verification

Run the narrowest check appropriate to your change. Gateway configuration and Lua changes should start with the OpenResty test suite; cross-service changes should then use the integration checks described in the public integration tests guide. Additional maintainer-only verification notes remain under dev/ and are not part of the GitBook documentation.

# Lua unit tests in a container; no local Lua installation is required
docker run --rm -v "$(pwd):/workspace" -w /workspace openresty/openresty:alpine-fat \
  luajit openresty/tests/run.lua

Use docker compose config --services and docker compose config --profiles to inspect the evaluated Compose surface before deploying.