From your first API call to production

0. Before you begin

Check the current Docker Desktop Windows requirements and terms. Windows Server is not this guide's supported path.

1. Verify the source kit

The supplier must provide the archive, its 64-character SHA-256, and revision over an authenticated channel. Replace the values below; stop before extraction or execution if they differ.

$Kit = Resolve-Path "$HOME\Downloads\Sentinel-Monitor-source-kit.zip"
$ExpectedSha256 = "paste-the-supplied-64-character-sha256-here"
$ActualSha256 = (Get-FileHash -LiteralPath $Kit -Algorithm SHA256).Hash.ToLowerInvariant()
if ($ActualSha256 -ne $ExpectedSha256.ToLowerInvariant()) {
  throw "Source-kit SHA-256 mismatch. Do not run this archive."
}

After extraction, compare its release manifest or git rev-parse HEAD. An archive without an out-of-band checksum/revision cannot be independently verified; request those artifacts.

2. Enable the WSL 2 backend

Open PowerShell as Administrator:

wsl --install --no-distribution

Restart, then return to Administrator PowerShell. The native PowerShell quickstart does not require a Linux distro; install Ubuntu only if you later choose the POSIX path.

wsl --update
wsl --set-default-version 2
wsl --version
wsl --status

If the current Windows build does not support --no-distribution, update WSL using Microsoft's guide. Installing Ubuntu is also valid, but it is not required for the native path. For recovery details, use Microsoft's WSL install guide.

3. Install and start Docker Desktop

1. Download only from the official Docker Windows installer.
2. For this flow, choose the per-user install and WSL 2 backend.
3. Open Docker Desktop from Start; installation does not mean its engine is running.
4. Wait for Engine running and confirm General → Use the WSL 2 based engine.
5. Only for the optional POSIX-in-Ubuntu path, enable that distro under Resources → WSL Integration and choose Apply & restart. Skip this for native PowerShell.

If WSL Integration is absent, switch Docker Desktop to Linux containers. Do not install a second Docker Engine inside Ubuntu; Docker documents the conflict.

docker version
docker compose version
docker info --format '{{.OSType}}'

docker version must show Client and Server, and OSType must be linux. Compose is docker compose (with a space); do not install legacy docker-compose.

4. Native PowerShell quickstart

Extract the verified kit under your user profile, such as C:\Users\you\Sentinel-Monitor. Avoid Program Files, OneDrive, and network shares; confirm backend, frontend, deploy, and docs exist.

Set-Location "$HOME\Sentinel-Monitor\deploy\api"
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\quickstart.ps1

It verifies the Linux Docker engine, creates a current-user-only .env, starts only api + mock-model, waits for readiness, and runs the no-Python first-Event plus SHA-256 proof.

API readiness passed.
PASS: evt_... -> ...sentinel-first-event-powershell.jpg (... bytes)
Quickstart complete. The API node remains running at http://127.0.0.1:8000.

Run a configuration preflight without starting containers (it securely creates .env when missing):

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\quickstart.ps1 -PreflightOnly

5. Accept the first run

docker compose ps
curl.exe --fail http://127.0.0.1:8000/healthz
curl.exe --fail http://127.0.0.1:8000/readyz

Both must return HTTP 200. Then open http://127.0.0.1:8000/v1/docs.

6. Continue integration without putting the key on the command line

The quickstart child process does not mutate its parent PowerShell. For later calls, load the key from the ACL-restricted .env only into the current shell, use PowerShell's HTTP client, and remove the variable immediately afterward:

$ApiKeyLine = Get-Content -LiteralPath .\.env |
  Where-Object { $_.StartsWith("SENTINEL_API_KEY=") } |
  Select-Object -First 1
if (-not $ApiKeyLine) { throw "SENTINEL_API_KEY is missing from .env" }

$env:SENTINEL_API_KEY = $ApiKeyLine.Substring("SENTINEL_API_KEY=".Length)
try {
  $Headers = @{ Authorization = "Bearer $env:SENTINEL_API_KEY" }
  Invoke-RestMethod -Uri "http://127.0.0.1:8000/v1/system" -Headers $Headers
} finally {
  Remove-Item Env:SENTINEL_API_KEY -ErrorAction SilentlyContinue
  Clear-Variable Headers, ApiKeyLine -ErrorAction SilentlyContinue
}

POSIX scripts: Ubuntu/WSL only

For POSIX operator scripts, keep a separate checkout at ~/Sentinel-Monitor (not /mnt/c), install Python 3 in Ubuntu, then run:

cd ~/Sentinel-Monitor
chmod +x deploy/api/*.sh deploy/api/recovery/*.sh
cd deploy/api
./quickstart.sh

Do not run this path from PowerShell, Command Prompt, Git Bash, or by double-clicking.

Common first-run failures

GPU facts, without fuzzy promises

The mock first run needs no GPU. deploy/api local_* is an NVIDIA/vLLM container path; Windows requires WSL 2, a supported NVIDIA GPU, current WSL kernel, and NVIDIA's WSL-capable Windows driver.

Docker currently supports Windows GPU-PV only with WSL2 + NVIDIA. AMD/Intel and native DirectML are not this Docker vLLM profile. NVIDIA also says not to install a Linux display driver inside WSL; install the Windows driver.

LAN, TLS, and Windows Firewall

Stop, reboot recovery, and uninstall

docker compose stop

stop preserves named volumes. Never add --volumes/-v or use docker system prune --volumes.

restart: unless-stopped cannot start Docker Desktop. After Windows reboots, containers recover only after Docker Desktop starts at sign-in. Enable Start Docker Desktop when you sign in if appropriate, then accept with a real reboot + readyz; this is not unattended pre-login recovery.

Clean-Windows completion criteria