Allow enter username and password for WSL account

This commit is contained in:
2026-11-16 22:59:54 +07:00
parent 62100913ae
commit e74d2eff3c
5 changed files with 129 additions and 88 deletions
+74 -67
View File
@@ -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.