Files
mini-pc-setup/Readme.md
T

101 lines
8.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# DTS Torque Vault — Mini PC Kiosk 24/7 Deployment
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.
---
## Repository Structure
mini-pc-setup/
├── 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
---
## Prerequisites
- **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`.
---
## Quick Start (Fresh Mini PC Deployment)
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**.
---
## What `install.bat` Configures
| 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. |
---
## Maintenance & Operations
### 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.
---
## Troubleshooting
- **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.