# Behind a proxy

> Learn how to install Wandelbots NOVA behind a proxy and set up your robot environment. Follow step-by-step instructions to prepare for seamless robot programming and automation.

If your VM or bare-metal instance accesses the internet through an HTTP/HTTPS proxy,
you need to configure the proxy at boot time before the NOVA installation begins.

> **Info:** This article applies to VM and bare-metal installations only.
> Cloud instances are managed by Wandelbots and do not require proxy configuration.

### Step 1: Configure the allowlist

Ensure the proxy allows the outbound HTTPS access to the following domains:

| Category | Domain | Purpose |
| - | - | - |
| NOVA installer | `get.wandelbots.io` | NOVA installer |
| | `galaxy.ansible.com` | Ansible roles and collections |
| | `*.amazonaws.com` | Ansible Galaxy storage |
| | `*.github.com` | Installer sources |
| | `release-assets.githubusercontent.com` | GitHub releases |
| NOVA Cloud | `portal.wandelbots.io` | Device activation and licensing |
| | `api.portal.wandelbots.io` | Portal API |
| | `auth.portal.wandelbots.io` | Portal authentication |
| Container registries | `wandelbots.azurecr.io` | NOVA images and app installs |
| | `wandelbots.germanywestcentral.data.azurecr.io`  add `*.blob.core.windows.net` for NOVA versions older than 26.5 as a fallback | ACR image layer downloads |
| | `auth.docker.io` | Docker Hub authentication |
| | `registry-1.docker.io` | Docker Hub registry |
| | `production.cloudflare.docker.com` | Docker Hub CDN |
| | `*.r2.cloudflarestorage.com` | Cloudflare R2 storage |
| OS package repositories | `*.almalinux.org` | AlmaLinux packages |
| | `*.fedoraproject.org` | EPEL packages |
| NOVA runtime services | `api.cryptlex.com`, `api.eu.cryptlex.com` | License validation |
| | `eu.i.posthog.com` | Analytics |
| | `standards-oui.ieee.org` | MAC address lookup |
| | `www.google.com` | Connectivity check |

> **Info:** Domains prefixed with `*.` indicate that all subdomains must be allowed.

### Step 2: Proxy URL format

```
http://[user:password@]host:port
```

1. Use the `http://` scheme even when the proxy handles HTTPS traffic,
   unless the proxy itself requires a TLS connection.
2. URL-encode special characters in credentials, e.g., `@` → `%40`, `#` → `%23`.

### Step 3: Set the proxy

#### Step 1: via boot parameter

Set the proxy directly in the boot menu.\
This is the simplest method and takes precedence over the ISO configuration file.

**UEFI boot (GRUB)**

1. In the boot menu, highlight **Install Wandelbots NOVA**.
2. Press **E** to edit the boot entry.
3. Find the line starting with `linuxefi` and append the proxy parameter:
   ```
   inst.proxy=http://proxyuser:proxypassword@10.1.2.3:3128
   ```
4. Press **Ctrl+X** or **F10** to boot.

**BIOS boot (isolinux)**

1. In the boot menu, highlight **Install Wandelbots NOVA**.
2. Press **Tab** to edit the boot command line.
3. Append the proxy parameter:
   ```
   inst.proxy=http://proxyuser:proxypassword@10.1.2.3:3128
   ```
4. Press **Enter** to boot.

To exclude hosts from the proxy, append `inst.no_proxy` to the same boot line:

```
no_proxy=localhost,127.0.0.1,.example.com
```

#### Step 2: via ISO configuration file

1. Embed the proxy settings in `wandelbots.cfg` inside the NOVA ISO image.\
   This is useful when you install on multiple machines with the same proxy.
2. Add or uncomment the following lines in `wandelbots.cfg`:
   ```ini
   PROXY_URL="http://proxyuser:proxypassword@10.1.2.3:3128"
   NO_PROXY="localhost,127.0.0.1,.local,.cluster.local"
   ```
3. Rebuild the ISO with the updated file.
   → The ISO will now include the proxy settings.
   Boot parameters override proxy settings if both are provided.

> **Info:** The proxy configuration is automatically persisted to the installed system. No additional proxy setup is needed after the installation completes.

### Troubleshooting

#### Installation hangs while downloading packages

The proxy cannot reach the AlmaLinux repositories.
Verify that `*.almalinux.org` and `*.fedoraproject.org` are allowed in the allowlist above.

#### NOVA installer fails on first boot

The proxy cannot reach `get.wandelbots.io` or related installer domains.
Check `/etc/wandelbots/proxy.env` and verify the NOVA installer domains in the allowlist above.

#### Device activation fails

The proxy cannot reach NOVA Cloud.
Verify that `portal.wandelbots.io`, `api.portal.wandelbots.io`,
and `auth.portal.wandelbots.io` are allowed in the allowlist above.

#### Container images fail to pull

The proxy cannot reach the container registry domains.
Verify that `wandelbots.azurecr.io`, `wandelbots.germanywestcentral.data.azurecr.io`,
and the Docker Hub domains are allowed in the allowlist above.