> 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/institutional-workflows/tutorial-first-lab-session.md).

# First lab session tutorial (EN)

This tutorial walks a new institution administrator through the complete end-to-end flow: deploying the gateway, connecting a physical lab computer, and watching a user reach an authenticated remote-desktop session.

**Estimated time:** 60–90 minutes for a first deployment on a fresh server.

**Prerequisites:** you have completed one of the installation guides and all containers are running (`docker compose ps` shows every service as `Up`).

***

## Overview

```mermaid
flowchart LR
    User["User browser / Marketplace"] --> Gateway["Institution server<br/>Lab Gateway"]
    Gateway --> OpenResty["OpenResty"]
    Gateway --> Guac["Guacamole"]
    Gateway --> Backend["blockchain-services"]
    Guac -- "internal RDP" --> LabPc["Windows lab computer<br/>Lab Station + app"]
    Backend --> Chain["Smart contracts<br/>reservation check"]
```

The gateway receives the user, validates their blockchain reservation, issues a session token, and opens an authenticated Guacamole window pointing at your lab computer.

***

## Part 1 — Register the institution as a lab provider

Provider registration follows a two-system handshake: the **Marketplace** generates a signed provisioning token, and the **Lab Gateway** applies it to complete the remote on-chain registration and the local configuration commit.

> **Precondition:** this tutorial assumes you deployed Lab Gateway in **provider+consumer mode** by following one of the [installation guides](https://github.com/DecentraLabsCom/lite-lab-gateway/tree/main/docs/install/README.md). If you installed in consumer-only mode, provider registration and lab publishing are not available.

### 1.1 Log into the Marketplace with institutional SSO credentials

Open `https://www.decentralabs-marketplace.app` and sign in using your institution's **eduGAIN / SSO credentials** (university username and password). You must have the **institution admin** role. If you do not yet have that role, contact the Marketplace platform administrator.

### 1.2 Generate a provisioning token in the Marketplace

1. Go to your **user dashboard** and find the **Institutional Provisioning Token** card.
2. Select token type **Provider**.
3. Enter the **public base URL of your Lab Gateway** (e.g. `https://lab.your-institution.edu`). This is the URL the Marketplace will use to reach your gateway's auth endpoints.
4. Click **Generate Provisioning Token**.
5. **Copy the token** — it is short-lived (typically 15–30 minutes) and single-use.

The token is a signed JWT issued by the Marketplace that encodes your institution name, email, country, organisation domain, and gateway URL. It also authorises the Marketplace to complete the on-chain provider registration on your behalf.

### 1.3 Apply the token in the wallet dashboard

1. Open `https://lab.your-institution.edu/wallet-dashboard`.
2. Enter your `ADMIN_ACCESS_TOKEN` when prompted.
3. Find the **Apply Provisioning Token** section and paste the token you copied.
4. Click **Apply**.

What happens next (automatically):

* `blockchain-services` validates the token signature against the Marketplace JWKS.
* `blockchain-services` calls back to the Marketplace to trigger on-chain registration: wallet address receives `PROVIDER_ROLE` and `INSTITUTION_ROLE`, and the gateway's auth endpoint is recorded in the smart contract.
* After the Marketplace confirms the transaction, `blockchain-services` writes the token-derived fields and `provider.registered` together as one atomic replacement of `config/provider.properties`. The dashboard shows **Provider Token Applied** only after this local snapshot is committed as well.

> If the local snapshot cannot be committed after the on-chain transaction, the endpoint returns a retryable `LOCAL_REGISTRATION_PERSISTENCE_FAILED` response. The previous properties snapshot is left intact; fix the filesystem/configuration issue and retry the same provisioning token so the Marketplace can reconcile its already-active registration without submitting a duplicate provider transaction.

***

## Part 2 — Connect the lab computer

### 2.1 Check network reachability

The gateway must be able to reach the lab computer on port 3389 (RDP). Test from the gateway host:

```bash
# Replace 192.168.1.100 with your lab computer's IP
nc -zv 192.168.1.100 3389
```

If using a separate network interface or VLAN, verify the routing is in place.

### 2.2 Prepare the lab computer (Windows)

1. Enable Remote Desktop: **Settings → System → Remote Desktop → Enable**.
2. Create a dedicated Windows user account for lab sessions (avoid using administrator accounts for day-to-day lab access).
3. Note the exact path of the Lab Station `AppControl.exe` and the window class name of the lab application. See the [Lab Station README](https://github.com/DecentraLabsCom/Lab-Station/blob/main/README.md) for instructions on how to find the window class.

### 2.3 Add a Guacamole connection

1. Open `https://lab.your-institution.edu/guacamole`.
2. Log in with the Guacamole admin credentials set during installation.
3. Go to **Settings → Connections → New Connection**.
4. Fill in:
   * **Name:** any descriptive name (e.g., `Electronics Lab 1`)
   * **Protocol:** RDP
   * **Hostname:** lab computer's IP address
   * **Port:** 3389
   * **Username:** Windows account username
   * **Password:** Windows account password
   * **Security mode:** Any
   * **Ignore server certificate:** checked
5. Under **Remote App:**
   * **Program:** `AppControl.exe` (or the full path if needed)
   * **Working directory:** path to the Lab Station folder on the Windows machine
   * **Parameters:** window class and lab application path — see Lab Station docs for details
6. Click **Save**.

### 2.4 Test the connection manually

Still in Guacamole admin view, click the connection name to open a direct session and confirm the desktop appears and the lab application launches.

***

## Part 3 — Publish the lab on the Marketplace

Lab publishing can be done from either the **Marketplace** or the local **Lab Manager**. Use Marketplace publishing when the provider has eduGAIN/SSO access. Use Lab Manager publishing when the provider was onboarded with a Marketplace invitation token but does not have an eduGAIN IdP.

### 3.0 Publish from Lab Manager

1. Open `https://lab.your-institution.edu/lab-manager`.
2. Enter your `LAB_MANAGER_TOKEN` when prompted.
3. In **Labs**, select an existing Guacamole connection or FMU discovered from the Gateway inventory.
4. Choose **Full Setup** to generate metadata and upload images/documents locally, or **Quick Setup** to reference an externally hosted metadata JSON.
5. Click **Publish Lab**. The Gateway stores generated metadata/assets under its persistent lab-content volume, exposes them at `/lab-content/...`, and signs the on-chain transaction with the institutional provider wallet.

### 3.1 Open the provider dashboard

1. Log into `https://www.decentralabs-marketplace.app` with your institutional SSO credentials.
2. Navigate to **Lab Panel** in the navbar. The lab management section is only visible to registered providers.
3. Click **Add New Lab**. A modal opens with two setup modes.

### 3.2 Choose a setup mode

#### Option A — Full Setup (recommended)

Fill in all lab details directly in the Marketplace form. No external files needed.

* **Basic Information:** lab name, description, keywords, category.
* **Pricing and availability:** hourly rate in service credits, available time slots, opening and closing dates.
* **Access information:** gateway access URI (your Lab Gateway URL) and access key.
* **Media:** upload images and documentation (up to 5 MB per file).

When you submit, the Marketplace sends a blockchain transaction that mints the lab on-chain and automatically stores the metadata. The lab is immediately bookable once the transaction confirms.

#### Option B — Quick Setup (advanced)

Use this mode if you already maintain a JSON metadata file hosted externally (IPFS, Arweave, GitHub Gist, your own server, etc.) and want to reference it directly rather than re-entering data in the form.

1. Host your JSON metadata file at a publicly accessible HTTPS URL.
2. In the **Quick Setup** tab, fill in the minimal on-chain fields (hourly rate, access URI, access key).
3. Paste the public URL to your JSON file in the **Metadata URL** field.
4. Submit — only the URL and on-chain fields are written to the contract.

> The JSON file is **optional in Full Setup** — the Marketplace generates and manages metadata storage automatically. It is only required in Quick Setup.

### 3.3 Confirm the lab appears in the Marketplace

After the transaction confirms, your lab should be listed when any user searches for your institution on `https://www.decentralabs-marketplace.app` and available for booking.

***

## Part 4 — End-to-end user flow

### 4.1 User makes a reservation

A user visits the Marketplace, finds your lab, and books a time slot. The smart contract records the reservation and assigns a `reservationKey`.

### 4.2 User authenticates at the gateway

At their booked start time, the user follows the **Access lab** link. This initiates the authentication flow:

1. The Marketplace sends a reservation-bound Marketplace JWT and SAML/WebAuthn evidence to the consumer/provider backend.
2. `blockchain-services` validates identity, PUC, reservation, time window and on-chain `ACCESS_AUTHORIZED` state as required by the selected flow.
3. The backend returns an opaque access code; OpenResty reserves it server-to-server, validates the returned JWT locally, and commits it only after the secure JTI session mapping is ready.
4. The browser is redirected to the selected gateway's Guacamole viewer without a JWT in the URL.

### 4.3 User reaches the lab desktop

The Guacamole window opens and shows the Windows desktop of the lab computer with the Lab Station application running. The user interacts with the remote lab in real time.

***

## Part 5 — Health and monitoring

### Check all services are running

```bash
docker compose ps
```

### Check gateway health

```bash
curl -k https://lab.your-institution.edu/health
```

### Check OIDC / JWKS metadata (Full/control-plane backend)

```bash
curl -k https://lab.your-institution.edu/.well-known/openid-configuration
curl -k https://lab.your-institution.edu/auth/jwks
```

In Lite mode these local `/auth` endpoints are intentionally blocked; inspect the configured remote issuer instead.

### Tail logs for a service

```bash
docker compose logs -f blockchain-services
docker compose logs -f openresty
```

***

## Troubleshooting

| Symptom                                                 | Likely cause                  | Fix                                                                                                           |
| ------------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------- |
| User lands on Guacamole login screen instead of session | JWT not accepted by Guacamole | Check `ISSUER` in `.env` matches the blockchain-services issuer shown at `/.well-known/openid-configuration`. |
| Reservation validation fails with 401                   | Contract address mismatch     | Verify `CONTRACT_ADDRESS` in `blockchain-services/.env` matches the deployed contract.                        |
| Guacamole shows "connection failed"                     | Lab computer unreachable      | Check network path and Windows firewall on the lab computer.                                                  |
| RDP session opens but Lab Station app does not start    | Wrong Remote App parameters   | Double-check the window class and path in the Guacamole connection settings.                                  |
| Wallet dashboard returns CORS error                     | Missing origin in allowlist   | Add the gateway URL to `CORS_ALLOWED_ORIGINS` in `.env` and `ALLOWED_ORIGINS` in `blockchain-services/.env`.  |

***

## Next steps

* [eduGAIN federation guide](/decentralabs-docs/lab-gateway/institutional-workflows/edugain-federation.md) — let institutional users log in with their university credentials
* [Installation guides](https://github.com/DecentraLabsCom/lite-lab-gateway/tree/main/docs/install/README.md) — other deployment modes