> 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/getting-started-and-deployment/installation/install-setup-script.md).

# Setup script (EN)

The setup script is the fastest way to get Lab Gateway running. It handles prerequisites, configuration files, secrets, and container startup in a single interactive session.

## Prerequisites

Install Docker/Compose, Git, and Python 3. Python 3 is used by the setup script to migrate the SAML environment configuration before the containers start.

| Requirement                                             | Minimum version                                                      |
| ------------------------------------------------------- | -------------------------------------------------------------------- |
| Docker Engine (Linux) or Docker Desktop (Windows/macOS) | 20.10+                                                               |
| Docker Compose plugin                                   | 2.14.0+ (`docker compose`; legacy `docker-compose` is not supported) |
| Git                                                     | any recent version                                                   |
| Python                                                  | 3.x                                                                  |
| 2 CPU cores, 4 GB RAM, 20 GB free disk                  | —                                                                    |

When Compose builds the Guacamole image locally, the Docker daemon's Linux kernel must provide `openat2` (upstream Linux 5.6+). See the [manual Compose guide](/decentralabs-docs/lab-gateway/getting-started-and-deployment/installation/install-manual-compose.md#linux-kernel-for-local-image-builds) for the scope and details; this is not a general minimum kernel for running already-built Gateway images.

Verify Docker is working before running the script:

```bash
docker --version
docker compose version
```

The setup script requires Docker Compose plugin 2.14.0 or newer. The current gateway has been tested with the v2.35.1 plugin. Run the setup script before starting Compose so it can generate the local files used by the Compose secrets.

The script creates the ignored `secrets/` directory from the credentials in `.env`, protects the directory with mode `0750`, and assigns the files to `HOST_UID:HOST_GID`. The files use mode `0644` because file-backed Compose secrets are direct mounts and several services run as image-specific non-root users whose UID may differ from `HOST_UID`; the directory still prevents unauthorized local users from reaching the files. Keep that directory on the host while the gateway is deployed; it must not be committed or deleted independently of the environment file.

## Step 1 — Clone the repository

```bash
git clone https://github.com/DecentraLabsCom/Lab-Gateway.git Lab-Gateway
cd Lab-Gateway
```

On Windows, clone to a path without spaces, for example `C:\lab-gateway`.

## Step 2 - Optional: add production TLS certificates

If you already have a certificate for the gateway domain, copy it into `certs/` before running setup:

```bash
mkdir -p certs
cp /path/to/fullchain.pem certs/fullchain.pem
cp /path/to/privkey.pem certs/privkey.pem
chmod 700 certs
chmod 600 certs/privkey.pem
chmod 644 certs/fullchain.pem
```

The setup script detects `certs/fullchain.pem` and `certs/privkey.pem`. If you skip this step, OpenResty generates self-signed certificates for development/local testing.

If you add or replace these files after the stack is running, restart OpenResty:

```bash
docker compose restart openresty
```

## Step 3 - Run the setup script

**Linux / macOS:**

```bash
chmod +x setup.sh
./setup.sh
```

**Windows:**

```cmd
setup.bat
```

## Step 4 - Answer the interactive prompts

The script guides you through the following steps automatically:

1. **Checks prerequisites and initialises submodules** — including the embedded `blockchain-services` repository.
2. **Creates and protects `.env` and `blockchain-services/.env`** — then generates distinct database, operator, redemption, observation, and Ops Worker secrets where needed.
3. **Configures the public edge** — domain, direct versus router/NAT ports, administrator access scope, Guacamole administration, and Lab Manager access.
4. **Selects Full or Lite mode** — an empty `ISSUER` creates a Full Gateway; an external `ISSUER` selects Lite mode. Lite setup requires a matching trust bundle issued by the remote Full control plane.
5. **Configures Lab Station operations and optional capabilities** — it asks for the private `WINRM_MANAGEMENT_CIDRS` allowlist used by local Stations and, on Linux, whether to activate the direct physical Station LAN WoL overlay. When enabled, it asks for the parent NIC, Station subnet, whether the VLAN has a router, the optional gateway address, and the reserved macvlan range. It writes `COMPOSE_FILE`, `WOL_LAN_PARENT`, `WOL_LAN_SUBNET`, and `WOL_LAN_IP_RANGE` to `.env`, plus `WOL_LAN_GATEWAY` when routed mode is selected. Leave the gateway empty for an isolated VLAN. On Windows, `setup.bat` leaves this Linux-only overlay disabled. The script then configures FMU access and, for Full Gateways, bundled, external, or disabled AAS support. Leave the CIDR empty only when no Ops hosts are configured yet.
6. **Offers a Cloudflare Tunnel** and starts the selected Compose services.

The script is interactive by design. For a repeatable non-interactive change, use the [manual Compose guide](/decentralabs-docs/lab-gateway/getting-started-and-deployment/installation/install-manual-compose.md) together with the [configuration reference](/decentralabs-docs/lab-gateway/getting-started-and-deployment/configuration.md).

## Step 5 - Verify the stack is running

```bash
docker compose ps
```

Core containers should show `Up`; optional profiles such as `fmu-runner`, `aas`, `certbot` or Cloudflare may be intentionally absent. Check the gateway health endpoint:

```bash
curl -k https://localhost/health
```

Compose-managed services, including `guacamole`, are configured with automatic restart policies. If the `fmu-local-dev` profile was enabled, its runner is also restarted after a Docker daemon or host restart. On Linux, also verify that Docker starts with the system:

```bash
sudo systemctl enable --now docker
```

On Windows, enable **Start Docker Desktop when you sign in** in Docker Desktop settings.

The public response is deliberately aggregate and safe for load balancers. A healthy edge reports `status: "UP"`; use `/gateway/health` for aggregate local access-plane readiness. After opening a Lab Manager session, use `/health/details` or `/gateway/health/details` for dependency diagnostics.

```json
{"status":"UP","service":"lab-gateway","mode":"full","public":true}
```

## Step 6 - Set up the institutional wallet

1. Open `https://your-domain/wallet-dashboard` in a browser.
2. Enter your `ADMIN_ACCESS_TOKEN` (set in `.env`) when prompted.
3. Click **Create wallet** (new institution) or **Import wallet** (existing key).
4. The encrypted wallet is stored in `blockchain-data/wallets.json` and loaded automatically on every restart.

![Wallet and billing dashboard](https://2324164250-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhBavBrPgRBmGJAMRBdoV%2Fuploads%2Fgit-blob-918f2f6d64fab446fa37ceea462bb4349f3db7e7%2Fwallet-dashboard.png?alt=media)

## Step 7 - Add your blockchain configuration

Edit `blockchain-services/.env` and set:

```env
CONTRACT_ADDRESS=0xYourDeployedContractAddress
ETHEREUM_SEPOLIA_RPC_URL=https://your-rpc-node
INSTITUTIONAL_WALLET_ADDRESS=  # leave empty — auto-filled after wallet creation
INSTITUTIONAL_WALLET_PASSWORD= # leave empty — auto-filled after wallet creation
ALLOWED_ORIGINS=https://your-domain.com
```

Restart the blockchain-services container to apply:

```bash
docker compose restart blockchain-services
```

## Step 8 - Configure a lab connection in Guacamole

See [Guacamole Connections](/decentralabs-docs/lab-gateway/architecture-and-connectivity/guacamole-connections.md) for the full step-by-step guide on adding RDP/VNC connections to your physical lab computers.

## Troubleshooting

| Symptom                                    | Fix                                                                                            |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| Container exits immediately                | Run `docker compose logs <service>` to see the error.                                          |
| MySQL fails to start                       | Check that passwords in `.env` are not set to default placeholder values (`CHANGE_ME`).        |
| `curl /health` returns TLS error           | Add `-k` for self-signed certs in development. In production, verify certificates in `certs/`. |
| Wallet dashboard asks for token repeatedly | Ensure `ADMIN_ACCESS_TOKEN` in `.env` is set and the browser is not blocking cookies.          |

## Next steps

* [Configure lab connections](/decentralabs-docs/lab-gateway/architecture-and-connectivity/guacamole-connections.md)
* [Manual Docker Compose installation](/decentralabs-docs/lab-gateway/getting-started-and-deployment/installation/install-manual-compose.md)
* [End-to-end operator tutorial](/decentralabs-docs/lab-gateway/institutional-workflows/tutorial-first-lab-session.md)
* [Operations and health](/decentralabs-docs/lab-gateway/operations-and-verification/operations-and-health.md)