README
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. Its documentation contract 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-servicesdeployment.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.
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.
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:
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 before materializing the Compose secret files:
Then run:
The setup and manual-installation guides explain the required values, wallet setup, TLS, Lite mode, and verification:
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:
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.
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/loginorPOST /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
Use the documentation guide for task-based navigation and the documentation contract 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.
Gateway operators and providers
Public installation, deployment, workflows and runbooks.
Backend integrators
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 is the GitBook/public index. Maintainer notes under dev/ are intentionally ignored and are not published.
Repository layout
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.
Use docker compose config --services and docker compose config --profiles to inspect the evaluated Compose surface before deploying.
Last updated