> For the complete documentation index, see [llms.txt](https://decentralabs-2.gitbook.io/decentralabs-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://decentralabs-2.gitbook.io/decentralabs-docs/lab-gateway/readme.md). # README [![Gateway Tests](https://github.com/DecentraLabsCom/Lab-Gateway/actions/workflows/gateway-tests.yml/badge.svg)](https://github.com/DecentraLabsCom/Lab-Gateway/actions/workflows/gateway-tests.yml) [![Security Scan](https://github.com/DecentraLabsCom/Lab-Gateway/actions/workflows/security.yml/badge.svg)](https://github.com/DecentraLabsCom/Lab-Gateway/actions/workflows/security.yml) [![Release](https://github.com/DecentraLabsCom/Lab-Gateway/actions/workflows/release.yml/badge.svg)](https://github.com/DecentraLabsCom/Lab-Gateway/actions/workflows/release.yml) 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 integrates the `blockchain-services` backend for a complete deployment. Start with the [documentation guide](/decentralabs-docs/lab-gateway/getting-started-and-deployment/docs.md). Its [documentation contract](https://github.com/DecentraLabsCom/lite-lab-gateway/tree/main/docs/documentation-contract.md) is the entry point for document ownership, 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. ```mermaid 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 ``` `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. ## Gateway entry page The public entry page exposes the three main browser surfaces: Lab Manager, lab access through Guacamole, and Wallet & Billing. The status badge reflects the aggregate readiness reported by the running Gateway. ![Lab Gateway entry page](https://2324164250-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhBavBrPgRBmGJAMRBdoV%2Fuploads%2Fgit-blob-ded9fc75287f7e6d0ddd34f92aad2dba606ea0d8%2Flab-gateway-home.png?alt=media) ## 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 `/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](/decentralabs-docs/lab-gateway/getting-started-and-deployment/deployment-architectures.md) 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: ```bash 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, and complete the persistent-directory prerequisites in the [manual Compose installation guide](/decentralabs-docs/lab-gateway/getting-started-and-deployment/installation/install-manual-compose.md) before materializing the Compose secret files: ```bash # Linux/macOS/WSL python3 scripts/validate-gateway-env.py --env .env bash scripts/sync-compose-secrets.sh ``` ```powershell # Windows PowerShell powershell -ExecutionPolicy Bypass -File .\scripts\Validate-GatewayEnv.ps1 -EnvPath .\.env powershell -ExecutionPolicy Bypass -File .\scripts\Sync-ComposeSecrets.ps1 ``` Then run: ```bash 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](/decentralabs-docs/lab-gateway/getting-started-and-deployment/installation/install-setup-script.md) / [Español](/decentralabs-docs/lab-gateway/getting-started-and-deployment/installation/instalar-setup-script.md) * [Manual Docker Compose — English](/decentralabs-docs/lab-gateway/getting-started-and-deployment/installation/install-manual-compose.md) / [Español](/decentralabs-docs/lab-gateway/getting-started-and-deployment/installation/instalar-compose-manual.md) * [NixOS compose-managed host — English](/decentralabs-docs/lab-gateway/getting-started-and-deployment/installation/install-nixos.md) / [Español](/decentralabs-docs/lab-gateway/getting-started-and-deployment/installation/instalar-nixos.md) ## 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](/decentralabs-docs/lab-gateway/getting-started-and-deployment/configuration.md). `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 an opaque access code with a short redemption lease. OpenResty reserves it server-to-server, validates the JWT and local destination/state, commits it only after validation, 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](/decentralabs-docs/lab-gateway/architecture-and-connectivity/laboratory-connectivity.md) and [operations and health](/decentralabs-docs/lab-gateway/operations-and-verification/operations-and-health.md) for the network and operator model. ## Documentation map * [Documentation guide](/decentralabs-docs/lab-gateway/getting-started-and-deployment/docs.md) — task-based navigation and terminology. * [Documentation contract](https://github.com/DecentraLabsCom/lite-lab-gateway/tree/main/docs/documentation-contract.md) — source ownership and cross-project consistency rules. * [Deployment architectures](/decentralabs-docs/lab-gateway/getting-started-and-deployment/deployment-architectures.md) — Full, Lite, composite, and standalone topologies. * [Configuration reference](/decentralabs-docs/lab-gateway/getting-started-and-deployment/configuration.md) — environment files, required secrets, profiles, and validation. * [Operations and health](/decentralabs-docs/lab-gateway/operations-and-verification/operations-and-health.md) — health endpoints, diagnostics, backups, and incident triage. * [Lab Manager energy operations](/decentralabs-docs/lab-gateway/architecture-and-connectivity/lab-manager-energy-operations.md) — credentials, APC/NETIO controllers, outlets, policies, testing, and rotation. * [Lab Manager operator guide](/decentralabs-docs/lab-gateway/architecture-and-connectivity/lab-manager-operator-guide.md) and [Labs and Operations](/decentralabs-docs/lab-gateway/architecture-and-connectivity/lab-manager-labs-and-operations.md) — tab-by-tab administration, host provisioning, reservations, and diagnosis. * [Lab Manager notifications](/decentralabs-docs/lab-gateway/architecture-and-connectivity/lab-manager-notifications.md) — separate Wallet & Billing administrator configuration. * [First lab session](/decentralabs-docs/lab-gateway/institutional-workflows/tutorial-first-lab-session.md) — provider journey from setup to an authenticated session. * [FMI/FMU support](/decentralabs-docs/lab-gateway/digital-twins/fmi-fmu-support.md) and [AAS support](/decentralabs-docs/lab-gateway/digital-twins/aas-support.md) — digital-twin capabilities. ## Repository layout ``` openresty/ Public edge, access-code exchange, and access guards blockchain-services/ 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](/decentralabs-docs/lab-gateway/operations-and-verification/integration.md) guide. Additional maintainer-only verification notes remain under `dev/` and are not part of the GitBook documentation. ```bash # 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.