diff --git a/CheckList.md b/CheckList.md index 4059951..1057bd4 100644 --- a/CheckList.md +++ b/CheckList.md @@ -1,6 +1,6 @@ # DTS Torque Vault — Mini PC Kiosk Commissioning & QA Checklist -Use this checklist to verify and sign off each Mini PC after running `scripts\install.bat`. +Use this checklist to verify and sign off each Mini PC after running `setup.bat` / `scripts\install.bat`. --- @@ -18,8 +18,8 @@ Use this checklist to verify and sign off each Mini PC after running `scripts\in ## 1. Pre-Deployment & Package Verification -- [ ] Deployment package extracted locally to `C:\Apps\mini-pc-setup\` (via `scripts\setup.bat` or manual archive extraction). -- [ ] All required files present: `scripts\install.bat`, `scripts\update.bat`, `scripts\uninstall.bat`, `templates\startup.html`, `compose.yml`, `.env`, `Readme.md`, and `CheckList.md`. +- [ ] Deployment package extracted locally to `C:\Apps\mini-pc-setup\` (via `setup.bat`, `bootstrap.ps1`, or manual release extraction). +- [ ] All required files present: `setup.bat`, `bootstrap.ps1`, `scripts\install.bat`, `scripts\update.bat`, `scripts\uninstall.bat`, `templates\startup.html`, `compose.yml`, `.env`, `README.md`, and `CheckList.md`. - [ ] BIOS Hardware Virtualization (`Intel VT-x` / `AMD-V`) verified as **Enabled**. - [ ] Active LAN / Wi-Fi connection confirmed. @@ -27,21 +27,22 @@ Use this checklist to verify and sign off each Mini PC after running `scripts\in ## 2. WSL2 & Docker Backend Verification -_(Sign in as **Administrator** via `Ctrl + Alt + Del` → **Switch user** to run these checks if needed)_ +_(Sign in as **Administrator** to run these checks if needed)_ -- [ ] `Ubuntu-22.04` WSL2 distribution is installed with `systemd=true` in `/etc/wsl.conf`. +- [ ] `Ubuntu-22.04` WSL2 distribution is installed with `systemd=true` in `/etc/wsl.conf` and `vmIdleTimeout=-1` in `%USERPROFILE%\.wslconfig`. - [ ] Docker Engine `28.3.2` and Docker Compose V2 are installed and pinned (`apt-mark hold`). -- [ ] All containers in `/opt/walmart` show status **`Up`** (`wsl -d Ubuntu-22.04 -u root bash -c "docker ps"`). -- [ ] Scheduled Task **`DTS_WSL_Docker_AutoStart`** exists, runs at startup (`AtStartup`), and executes under **`SYSTEM`**. +- [ ] All containers in `/opt/walmart` (`-p walmart`) show status **`Up`** (`wsl -d Ubuntu-22.04 -u root bash -c "docker ps"`). +- [ ] Backend health endpoint `http://localhost:3000/api/v1/system/health-check/` returns **`Online`**. +- [ ] Scheduled Task **`WSL Docker Startup`** exists, triggers **At startup**, runs under the **Administrator** account (_Run whether user is logged on or not_, **not** `SYSTEM`), and has **Stop the task if it runs longer than** & **AC power** conditions **unchecked**. --- ## 3. Kiosk Mode, Auto-Logon & Session Persistence -- [ ] **Cold Boot / Reboot Test:** Restart the Mini PC and verify it bypasses the Windows login screen and automatically signs into the Kiosk account. -- [ ] **UI Lockdown:** Windows Desktop, Start Menu, and Taskbar are completely hidden; Microsoft Edge launches full-screen on `C:\KioskApp\startup.html` and transitions smoothly into the main application. +- [ ] **Cold Boot / Reboot Test:** Restart the Mini PC and verify it bypasses the Windows login screen and automatically signs into the Kiosk account (`Torque Vault`). +- [ ] **UI Lockdown:** Windows Desktop, Start Menu, and Taskbar are completely hidden; Microsoft Edge launches full-screen on `C:\KioskApp\startup.html` and transitions smoothly into `http://localhost:3000`. - [ ] **Session Persistence Test:** Log into the web application inside Kiosk mode, reboot the Mini PC, and confirm the browser session/cookies in `C:\KioskBrowserData` remain intact (no forced re-login). -- [ ] **Admin Escape Hatch:** Pressing `Ctrl + Alt + Del` → **Switch user** allows signing into the **Administrator** account with a normal Windows Desktop intact. +- [ ] **Admin Escape Hatch:** Pressing `Ctrl + Alt + Del` → **Switch user** (or turning the display off/on and swiping up the Lock Screen on touch-only kiosks) allows signing into the **Administrator** account with a normal Windows Desktop intact. --- @@ -59,4 +60,4 @@ _(Sign in as **Administrator** via `Ctrl + Alt + Del` → **Switch user** to run - [ ] **PASS — Unit approved for production deployment.** -**Technician Signature:** `___________________________`     **Date:** `____ / ____ / 2026` +**Technician Signature:** `___________________________`     **Date:** `____ / ____ / ____` diff --git a/Readme.md b/Readme.md index 8d19a2f..be42bd9 100644 --- a/Readme.md +++ b/Readme.md @@ -1,93 +1,100 @@ -# DTS Torque Vault — Mini PC Kiosk Deployment & Maintenance Guide (24/7) +# DTS Torque Vault — Mini PC Kiosk 24/7 Deployment -Automated, idempotent deployment scripts to provision a fresh Windows Mini PC into a dedicated **24/7 Kiosk appliance** running WSL2 (`Ubuntu-22.04`), Docker Engine `28.3.2`, and full-screen Microsoft Edge with persistent session storage. +Automated, zero-touch deployment suite for provisioning Windows 10/11 Mini PCs into dedicated 24/7 Kiosk terminals running **DTS Torque Vault** on WSL2 (`Ubuntu-22.04`) and Docker Engine. --- -## 1. Repository & Deployment Structure +## Repository Structure mini-pc-setup/ - ├── .gitignore # Prevents committing real .env credentials - ├── .env.template # Environment variable template (copied to .env on setup) - ├── compose.yml # Docker Compose service definitions - ├── Readme.md # Technician deployment & maintenance guide - ├── CheckList.md # Unit commissioning & QA sign-off checklist - ├── templates/ - │ └── startup.html # Kiosk splash/health-check screen before app redirect - └── scripts/ - ├── setup.bat # 1-click Gitea Latest Release bootstrapper for technicians - ├── bootstrap.ps1 # Downloads Latest Release to C:\Apps\mini-pc-setup\ - ├── install.bat # Master all-in-one deployment script - ├── update.bat # Updates containers, configs, and startup.html - └── uninstall.bat # Reverts Kiosk mode and restores normal Windows - -> **Critical Pre-Deployment Notes** -> -> - **Administrator & Internet:** Sign in using a local **Administrator** account with an active Internet connection. -> - **BIOS Virtualization:** Hardware Virtualization (`Intel VT-x` or `AMD-V`) must be enabled in BIOS. -> - **Local Execution:** All files are extracted to `C:\Apps\mini-pc-setup\` so installation survives the mandatory WSL2 reboot without requiring a USB drive to remain plugged in. + ├── setup.bat # One-click Windows bootstrapper (downloads & extracts latest release) + ├── bootstrap.ps1 # PowerShell release downloader & .env initializer + ├── compose.yml # Docker Compose service definitions (project: walmart) + ├── .env.template # Environment variable template (copied to .env if missing) + ├── README.md # Deployment & maintenance guide + ├── scripts/ + │ ├── install.bat # Master 7-phase Kiosk & WSL2/Docker installer + │ ├── update.bat # Zero-downtime container & image updater (preserves DB volumes) + │ └── uninstall.bat # Full system restore & Kiosk uninstaller (Auto Wipe or Custom) + └── templates/ + └── startup.html # Local Kiosk splash/health-check screen before redirecting to :3000 --- -## 2. Fresh Mini PC Installation +## Prerequisites -### Option A: 1-Click Deployment via Gitea Latest Release _(Recommended)_ - -1. Copy **`scripts\setup.bat`** onto the Mini PC (or download it from the Gitea Release Assets). -2. Double-click **`setup.bat`** and click **Yes** on the UAC Administrator prompt. - - If the repository is **Private**, enter your Gitea credentials once when prompted. -3. The bootstrapper downloads the Latest Release into `C:\Apps\mini-pc-setup\`, copies `.env.template` to `.env` (opening Notepad so you can configure site-specific values), and launches `scripts\install.bat`. - -### Option B: Manual Deployment from `C:\Apps\mini-pc-setup\` - -1. Extract the release package to `C:\Apps\mini-pc-setup\`. -2. Double-click **`scripts\install.bat`** (auto-creates `.env` from `.env.template` if missing). - -### Installation Phases (`scripts\install.bat`) - -1. **Pre-Flight Checks:** Verifies `templates\startup.html`, `compose.yml`, `.env`, Microsoft Edge, Internet access, and BIOS Virtualization. -2. **Phase 1 — WSL2 & Ubuntu-22.04 _(First-time setup only)_:** Installs WSL2 + `Ubuntu-22.04`, registers a `RunOnce` resume entry, and reboots. Sign back in as **Administrator** and the installer automatically resumes. -3. **Phase 2 — Docker, Containers & Kiosk Setup:** - - Logs into `gitea.digitoolsolutions.synology.me`, deploys containers to `/opt/walmart`, and registers the `DTS_WSL_Docker_AutoStart` (`SYSTEM`) boot task. - - Prompts for the Kiosk username (default: `Torque Vault`) and optional password _(avoid Batch special characters `&`, `|`, `<`, `>`, `^`, `%`)_. If switching to a new Kiosk username, the previous Kiosk user's normal Windows Desktop is automatically restored. - - Hardens 24/7 operation: activates **High Performance** power plan, disables **Sleep**, **Hibernate**, **Display Timeout**, and **USB Selective Suspend**, and blocks Windows Update auto-reboots while logged on. -4. **Final Reboot:** Type `Y` and press **Enter**. The Mini PC boots directly into the full-screen Kiosk application. +- **OS:** Windows 10 (21H2+) or Windows 11 (64-bit) with **Microsoft Edge** installed. +- **BIOS / Firmware:** Hardware Virtualization (`Intel VT-x` / `AMD-V`) **Enabled**. +- **Privileges:** Local Administrator account on the Mini PC. +- **Network:** Internet access to download Ubuntu/Docker packages and pull images from `gitea.digitoolsolutions.synology.me`. --- -## 3. Switching to Administrator for Maintenance +## Quick Start (Fresh Mini PC Deployment) -While the Mini PC is running in full-screen Kiosk mode: - -1. Press **`Ctrl + Alt + Del`**. -2. Click **Switch user**. -3. Select the **Administrator** account in the bottom-left corner and sign in. +1. Copy **`setup.bat`** onto the Mini PC (or download it directly from Gitea) and double-click to run it (automatically elevates to Administrator). +2. `setup.bat` performs the following automatically: + - Verifies DNS and connectivity to `[https://gitea.digitoolsolutions.synology.me](https://gitea.digitoolsolutions.synology.me)`. + - Fetches the latest published release of `lamtruong28/mini-pc-setup` (prompts for Gitea credentials only if the repository/release is private). + - Extracts all release assets (including hidden files such as `.env`) into **`C:\Apps\mini-pc-setup`**. + - Launches `scripts\install.bat`. +3. **If WSL2 / `Ubuntu-22.04` is not installed yet:** + - Phase 1 installs WSL2 and `Ubuntu-22.04`, registers a `RunOnce` resume entry, and prompts to **reboot** the Mini PC. + - Log back in as Administrator after reboot — `install.bat` resumes automatically. +4. **During installation (`install.bat`):** + - If `.env` does not exist, it is created from `.env.template` and opened in Notepad for configuration. + - Enter your Gitea registry credentials when prompted by `docker login`. + - Choose the Windows Kiosk account name (**Default:** `Torque Vault`) and password (**Default:** blank / no password). +5. When prompted at the end, enter **`Y`** to reboot immediately into **Fullscreen Edge Kiosk Mode**. --- -## 4. Updating the Application (`scripts\update.bat`) +## What `install.bat` Configures -1. Switch to the **Administrator** account (see [Section 3](#3-switching-to-administrator-for-maintenance)). -2. Update `compose.yml`, `.env`, or `templates\startup.html` in `C:\Apps\mini-pc-setup\` if changed. -3. Double-click **`scripts\update.bat`**. -4. **Verification:** Confirm all 4 steps complete and `docker ps` shows all containers in the `Up` state. Reboot to reload the Kiosk UI. +| Phase | Component | Configuration Details | +| :------------ | :---------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Pre-Check** | Environment & Security | Verifies Edge, `compose.yml`, `.env`, `templates\startup.html`, Internet, BIOS Virtualization, and locks `C:\Apps\mini-pc-setup` ACLs to `Administrators` and `SYSTEM`. | +| **Phase 1–2** | WSL2 (`Ubuntu-22.04`) | Installs `Ubuntu-22.04`, creates `dtsadmin` with passwordless `sudo`, enables `systemd=true`, and sets `vmIdleTimeout=-1` in `.wslconfig`. | +| **Phase 3** | Docker Engine | Installs and holds pinned `docker-ce` (`5:28.3.2-1~ubuntu.22.04~jammy`) + `docker-compose-plugin`. | +| **Phase 4** | App Deployment | Deploys stack under `-p walmart` in `/opt/walmart` and polls `http://localhost:3000/api/v1/system/health-check/` every 30s until `"Online"` is returned. | +| **Phase 5–6** | Kiosk Shell & Boot Task | Creates `Torque Vault` user, sets Windows `AutoAdminLogon`, locks user `Shell` policy directly to fullscreen Edge (`C:\KioskApp\startup.html` → `http://localhost:3000`), and registers the **`WSL Docker Startup`** Task Scheduler job (`AtStartup`, `S4U`, unlimited runtime) running `C:\KioskApp\start_wsl_docker.bat`. | +| **Phase 7** | 24/7 Hardening | Activates High Performance power plan, disables sleep/hibernate/display/disk timeouts, and blocks automatic Windows Update reboots while logged on. | --- -## 5. Uninstalling / Restoring Normal Windows Mode (`scripts\uninstall.bat`) +## Maintenance & Operations -1. Switch to the **Administrator** account (see [Section 3](#3-switching-to-administrator-for-maintenance)). -2. Double-click **`scripts\uninstall.bat`**. -3. Answer the cleanup prompts (`Y`/`N`) for deleting the Kiosk user account, removing `C:\KioskApp` & `C:\KioskBrowserData`, and unregistering `Ubuntu-22.04`. -4. Type `Y` to reboot. Windows returns to the standard login screen with Auto-Logon disabled and the power plan reset to **Balanced**. +### Updating the Application (`scripts\update.bat`) + +To update container images, `compose.yml`, `.env`, or `templates\startup.html` without losing database data: + +1. Log in to the Administrator account (press `Ctrl + Alt + Del` → **Sign out** or **Switch user**). +2. Update `.env` or `compose.yml` inside `C:\Apps\mini-pc-setup` if needed. +3. Run **`C:\Apps\mini-pc-setup\scripts\update.bat`** as Administrator: + - Syncs `startup.html`, `compose.yml`, and `.env` (converting CRLF to LF). + - Runs `docker compose -p walmart pull` and `up -d --remove-orphans` (preserving database volumes). + - Verifies `/api/v1/system/health-check/` reports `Online` and prunes dangling Docker images. + +### Uninstalling & Restoring Desktop (`scripts\uninstall.bat`) + +Run **`C:\Apps\mini-pc-setup\scripts\uninstall.bat`** as Administrator and select a mode: + +- **`[1] Auto Wipe All`:** Automatically disables Auto-Logon, deletes the Kiosk user and browser profile (`C:\KioskBrowserData`), removes scheduled tasks and `C:\KioskApp`, tears down Docker containers and volumes (`down -v`), restores Balanced power plan, and deletes `C:\Apps\mini-pc-setup`. +- **`[2] Manual / Custom`:** Prompts step-by-step whether to delete or restore the Kiosk user's normal Windows Desktop (`explorer.exe`), keep browser data, preserve database volumes, or keep the setup folder. --- -## 6. Quick Troubleshooting +## Troubleshooting -| Symptom | Resolution | -| :------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------- | ------------------------- | -| **`Hardware Virtualization is DISABLED in BIOS`** | Reboot into BIOS/UEFI, enable **Intel VT-x** or **AMD-V**, save, and re-run `scripts\install.bat`. | -| **Kiosk stays on `startup.html` for > 1 minute** | Verify LAN/Wi-Fi connectivity. Switch to Administrator and run `scripts\update.bat` to verify containers in `/opt/walmart`. | -| **Stops at Windows login screen (no Auto-Logon)** | Sign in as Administrator and re-run `scripts\install.bat`. Ensure the Kiosk password does not contain `&`, ` | `, `<`, `>`, `^`, or `%`. | -| **USB Dongle / Scanner disconnects when idle** | Re-run `scripts\install.bat` to ensure **High Performance** is active and **USB Selective Suspend** is **Disabled**. | +- **Web app (`http://localhost:3000`) is unreachable after reboot:** + - Open **Task Scheduler** as Administrator and check **`WSL Docker Startup`**. Ensure it is configured to run under the Administrator account that installed WSL2 (not `SYSTEM`) with _"Run whether user is logged on or not"_ enabled. + - Inspect backend container logs inside WSL: + + wsl -d Ubuntu-22.04 -u root docker logs tv-backend-prod + +- **Exiting Kiosk Mode for Admin Maintenance:** + - **With a physical keyboard:** Press **`Ctrl + Alt + Del`** → **Switch user** → sign in with your Administrator account. + - **Touchscreen only (no physical keyboard):** + 1. Turn the display off and back on (or press the physical power/sleep button briefly to lock the screen). + 2. Swipe up on the Windows Lock Screen to reveal the sign-in screen. + 3. Tap the **Administrator** account in the bottom-left corner, tap the password box (Windows On-Screen Touch Keyboard will appear automatically), and sign in. diff --git a/scripts/bootstrap.ps1 b/bootstrap.ps1 similarity index 100% rename from scripts/bootstrap.ps1 rename to bootstrap.ps1 diff --git a/scripts/install.bat b/scripts/install.bat index 4c6d6f8..e37dc57 100644 --- a/scripts/install.bat +++ b/scripts/install.bat @@ -10,7 +10,7 @@ set "CLEAN_ROOT=%ROOT_DIR:~0,-1%" :: WSL2 & Docker Engine Settings set "WSL_DISTRO=Ubuntu-22.04" -set "WSL_USER=dtsadmin" +set "DEFAULT_WSL_USER=gateway" set "DOCKER_VERSION=5:28.3.2-1~ubuntu.22.04~jammy" :: Project & Health-Check Polling Settings @@ -136,20 +136,53 @@ if %errorLevel% neq 0 ( ) :: ============================================================================ -:: PHASE 2: INITIALIZE UBUNTU USER, SYSTEMD & VMIDLETIMEOUT IN WSL2 +:: PHASE 2: INITIALIZE UBUNTU USER (WITH PASSWORD), SYSTEMD & VMIDLETIMEOUT :: ============================================================================ -echo [1/7] Initializing %WSL_DISTRO%, enabling systemd and disabling VM idle timeout... -powershell -NoProfile -ExecutionPolicy Bypass -Command ^ - "$wslCfg = Join-Path $env:USERPROFILE '.wslconfig';" ^ - "Set-Content -Path $wslCfg -Value \"[wsl2]`r`nvmIdleTimeout=-1\" -Encoding Ascii" +echo [1/7] Initializing %WSL_DISTRO%, configuring Linux user, systemd and VM idle timeout... -wsl -d %WSL_DISTRO% -u root bash -c ^ - "id -u %WSL_USER% >/dev/null 2>&1 || (useradd -m -s /bin/bash -G sudo %WSL_USER% && echo '%WSL_USER% ALL=(ALL) NOPASSWD:ALL' > /etc/sudoers.d/%WSL_USER%)" -wsl -d %WSL_DISTRO% -u root bash -c ^ - "printf '[user]\ndefault=%WSL_USER%\n[boot]\nsystemd=true\n' > /etc/wsl.conf" +set "WSL_USER=" +set /p WSL_USER="Enter Linux username for WSL [Default: %DEFAULT_WSL_USER%]: " +if "%WSL_USER%"=="" set "WSL_USER=%DEFAULT_WSL_USER%" + +if /i "%WSL_USER%"=="root" goto :ERR_WSL_ROOT + +set "WSL_PASS=" +set /p WSL_PASS="Enter Linux sudo password for '%WSL_USER%' [Default: Dts@2026]: " +if "%WSL_PASS%"=="" set "WSL_PASS=Dts@2026" + +powershell -NoProfile -ExecutionPolicy Bypass -Command "$wslCfg = Join-Path $env:USERPROFILE '.wslconfig'; Set-Content -Path $wslCfg -Value \"[wsl2]`r`nvmIdleTimeout=-1\" -Encoding Ascii" + +set "STEP1_SH=%TEMP%\dts_step1.sh" +> "%STEP1_SH%" echo set -e +>> "%STEP1_SH%" echo WSL_USR="$1" +>> "%STEP1_SH%" echo WSL_PWD="$2" +>> "%STEP1_SH%" echo id -u "$WSL_USR" ^>/dev/null 2^>^&1 ^|^| useradd -m -s /bin/bash -G sudo "$WSL_USR" +>> "%STEP1_SH%" echo echo "${WSL_USR}:${WSL_PWD}" ^| chpasswd +>> "%STEP1_SH%" echo rm -f "/etc/sudoers.d/${WSL_USR}" +>> "%STEP1_SH%" echo printf '[user]\ndefault=%%s\n[boot]\nsystemd=true\n' "$WSL_USR" ^> /etc/wsl.conf + +for /f "delims=" %%i in ('wsl -d %WSL_DISTRO% -u root wslpath -a "%STEP1_SH%"') do set "WSL_STEP1_SH=%%i" +wsl -d %WSL_DISTRO% -u root bash -c "tr -d '\r' < '%WSL_STEP1_SH%' > /tmp/dts_step1.sh && bash /tmp/dts_step1.sh '%WSL_USER%' '%WSL_PASS%'; RC=$?; rm -f /tmp/dts_step1.sh; exit $RC" +set "STEP1_ERR=%errorLevel%" +del /f /q "%STEP1_SH%" >nul 2>&1 + +if %STEP1_ERR% neq 0 goto :ERR_WSL_USER wsl --terminate %WSL_DISTRO% >nul 2>&1 timeout /t 2 /nobreak >nul +goto :PHASE2_DONE + +:ERR_WSL_ROOT +echo [ERROR] Cannot use root as the standard WSL user! +pause +exit /b 1 + +:ERR_WSL_USER +echo [ERROR] Failed to create or configure Linux user "%WSL_USER%". +pause +exit /b 1 + +:PHASE2_DONE :: ============================================================================ :: PHASE 3: INSTALL & PIN DOCKER ENGINE + COMPOSE V2 (DIRECT .SH + DYNAMIC PARAMS) diff --git a/scripts/setup.bat b/setup.bat similarity index 100% rename from scripts/setup.bat rename to setup.bat