> ## Documentation Index
> Fetch the complete documentation index at: https://docs.novosky.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Windows VM (Docker + noVNC)

> Run the MT5 Windows environment inside Docker on a Linux host using dockurr/windows, with browser-based desktop access via noVNC and Caddy reverse proxy.

## Overview

Instead of a separate Windows machine, NOVOSKY can run the MT5 terminal inside a KVM-accelerated Windows VM managed by Docker. The VM is controlled with a single command and its desktop is accessible from any browser via noVNC, password-protected by Caddy.

| Component         | Role                                                   |
| ----------------- | ------------------------------------------------------ |
| `dockurr/windows` | Windows 11 VM with KVM acceleration                    |
| noVNC             | Browser-based desktop viewer (port 8006 internally)    |
| Caddy             | Reverse proxy — exposes port 8006 with HTTP basic auth |
| `setup-vm.sh`     | Orchestrates the whole stack (`make up`)               |

***

## Prerequisites

* Linux host with KVM enabled (`/dev/kvm` must exist)
* Docker and Docker Compose installed
* Ports 80, 443, and `NOVNC_PORT` (default 8006) open on the host firewall

To verify KVM is available:

```bash theme={null}
ls /dev/kvm
```

If the file is missing, enable virtualization in your BIOS/UEFI settings.

***

## Configuration

Add these to your `.env` before the first `make up`:

```bash theme={null}
# Port the noVNC browser interface listens on
NOVNC_PORT=8006

# Password shown in the browser login prompt at :8006
VNC_PASS=your_password_here
```

| Variable     | Required | Default | Description                                                              |
| ------------ | -------- | ------- | ------------------------------------------------------------------------ |
| `NOVNC_PORT` | No       | `8006`  | Host port Caddy binds for noVNC                                          |
| `VNC_PASS`   | No       | —       | Browser login password. If unset, noVNC is accessible without a password |

<Warning>
  Set `VNC_PASS` before exposing the server to the internet. Without it, anyone who can reach the port sees the Windows desktop.
</Warning>

***

## Starting the VM

```bash theme={null}
make up
```

This runs `setup-vm.sh`, which:

1. Sources `.env` to read `VNC_PASS` and other variables
2. Generates `docker-compose.override.yml` with the correct API port mappings
3. Bcrypt-hashes `VNC_PASS` using the Caddy image and writes a Caddyfile with `basicauth`
4. Starts the `mt5` (Windows VM) and `caddy` containers
5. Waits for the VM health check to pass

First boot takes 10–15 minutes while Windows installs. Subsequent starts are under a minute.

<Note>
  `setup-vm.sh` only updates `.env` when a managed key (`API_TOKEN`, `NOVNC_PORT`) has actually changed. It will not overwrite `VNC_PASS` or other keys you have set manually.
</Note>

***

## Accessing the desktop

Once `make up` completes, open a browser and go to:

```
http://<your-server-ip>:8006
```

A login prompt appears. Enter:

| Field    | Value                 |
| -------- | --------------------- |
| Username | `admin`               |
| Password | your `VNC_PASS` value |

After login you see the full Windows desktop running inside the VM.

***

## Port and network architecture

The `mt5` container does not expose port 8006 directly on the host. All external traffic goes through Caddy:

```
Browser → host:8006 → Caddy → mt5:8006 (noVNC, internal)
Browser → host:443  → Caddy → mt5:<api_port> (MT5 REST API, HTTPS)
```

MT5 REST API ports are added dynamically from `config/terminals.json` via `docker-compose.override.yml` — they bypass Caddy and bind directly on the host.

***

## Stopping and restarting

```bash theme={null}
# Stop all containers (VM state is preserved on disk)
docker compose down

# Start again (fast — no reinstall)
make up

# Full wipe (deletes the VM disk image)
make distclean
```

<Warning>
  `make distclean` deletes `data/storage/data.img` — the VM disk. Windows will reinstall from scratch on the next `make up`. Use only when you want a clean slate.
</Warning>

***

## Changing the noVNC password

1. Update `VNC_PASS` in `.env`
2. Run `make up` — `setup-vm.sh` detects the change, regenerates the Caddyfile with the new hash, and restarts Caddy

No VM restart is needed; only Caddy reloads.