> 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 the one-shot `ops-schema-migrator`, `openresty`, `blockchain-services` (dormant in Lite mode), `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 with optional bundled AAS sync; never production | `FMU_RUNNER_ENABLED=true FMU_LOCAL_REALTIME_ENABLED=true docker compose --profile fmu-local-dev --profile aas up -d` | | `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. When testing AAS with the local runner, start the `aas` profile alongside `fmu-local-dev`; the local runner reaches only the internal bundled BaSyx network and keeps the Station/control-plane isolation. 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 Use the [documentation guide](/decentralabs-docs/lab-gateway/getting-started-and-deployment/docs.md) for task-based navigation and the [documentation contract](https://github.com/DecentraLabsCom/lite-lab-gateway/tree/main/docs/documentation-contract.md) when a change crosses the Gateway, backend, Marketplace or contracts. The guide links to the owning documents for deployment, configuration, operations, Lab Manager, institutional access, FMU and AAS; this page deliberately keeps only the entry points. | Audience | Start here | Scope | | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | Gateway operators and providers | [Documentation guide](/decentralabs-docs/lab-gateway/getting-started-and-deployment/docs.md) | Public installation, deployment, workflows and runbooks. | | Backend integrators | [Backend documentation index](https://github.com/DecentraLabsCom/lite-lab-gateway/tree/main/blockchain-services/SUMMARY.md) | API, authentication, billing and backend deployment contracts. | | Maintainers | `dev/` (local-only) and the relevant public owning document | Test notes and design records; private notes are not protocol specifications. | The root [SUMMARY.md](https://github.com/DecentraLabsCom/lite-lab-gateway/tree/main/SUMMARY.md) is the GitBook/public index. Maintainer notes under `dev/` are intentionally ignored and are not published. ## 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.