Update Readme.md, CheckList.md files

This commit is contained in:
2026-11-18 22:02:26 +07:00
parent 4b9c8a87ec
commit 5633bdcc56
2 changed files with 117 additions and 84 deletions
+70 -73
View File
@@ -1,100 +1,97 @@
# DTS Torque Vault — Mini PC Kiosk 24/7 Deployment
# DTS Torque Vault — Mini PC Kiosk 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.
Deployment and maintenance guide for Windows Mini PCs running DTS Torque Vault in Edge kiosk mode, with the application stack hosted by Docker Engine inside WSL2.
---
## Repository contents
## Repository Structure
```text
mini-pc-setup/
├── setup.bat # Downloads and extracts the latest Gitea release
├── compose.yml # Docker Compose stack (project name: walmart)
├── .env.template # Sample configuration used to create .env
├── CheckList.md # Commissioning and QA checklist
├── scripts/
│ ├── install.bat # Installs and configures WSL2, Docker, and kiosk mode
│ ├── update.bat # Pulls images and updates the Compose stack
│ └── uninstall.bat # Removes kiosk configuration and/or application data
└── templates/
└── startup.html # Local startup screen that waits for the web app
```
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
The installer creates a hidden `.env` file from `.env.template` if `.env` is missing. The sample file is then removed from the deployment directory. Keep `.env` private: it contains application and database settings, including secrets. Docker registry credentials are entered separately at the login prompt.
---
## Requirements
## Prerequisites
- 64-bit Windows 10 or Windows 11, with Microsoft Edge installed.
- A local Windows Administrator account. Run deployment while signed in to the administrator account that should own the WSL startup task.
- CPU virtualization enabled in BIOS/UEFI.
- Internet access for Gitea, Ubuntu/WSL, Docker packages, and container images.
- **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`.
## Fresh deployment
---
1. Run `setup.bat` as Administrator, or extract a release and run `scripts\install.bat` as Administrator.
- `setup.bat` downloads the latest release of `lamtruong28/mini-pc-setup` from `https://gitea.digitoolsolutions.synology.me` and extracts it to `C:\Apps\mini-pc-setup`.
- If the release requires authentication, the bootstrapper prompts for Gitea credentials.
- **Warning:** `setup.bat` deletes the existing `C:\Apps\mini-pc-setup` directory before extracting. Back up any local configuration or files there first.
2. On the first install, review and complete `.env` in Notepad when prompted. Configure the image names and all application, database, Redis, and Watchtower values required by your deployment. Do not put production credentials in a shared release.
3. If WSL2 or `Ubuntu-22.04` is not ready, the installer installs it, creates a logon-triggered resume task, and reboots Windows. Sign back in to the same Administrator account; the installer resumes automatically.
4. Follow the prompts:
- Enter a non-root Linux username and a sudo password for WSL (the suggested username is `gateway`).
- Sign in to the Docker registry when prompted.
- Select a separate Windows kiosk account (default name: `Torque Vault`) and optionally set its password.
- Choose the display-off timeout in minutes (default: 15; enter `0` to keep the display on).
5. At completion, enter `Y` to reboot into kiosk mode.
## Quick Start (Fresh Mini PC Deployment)
## What the installer configures
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**.
| Stage | Configuration |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Pre-check | Verifies Edge, required configuration files, Internet connectivity, and virtualization; restricts the deployment folder ACLs to Administrators and SYSTEM. |
| WSL2 | Installs/starts `Ubuntu-22.04`, configures the selected Linux user, enables systemd, and sets `vmIdleTimeout=-1` in the administrator's `.wslconfig`. |
| Docker | Installs Docker Engine `5:28.3.2-1~ubuntu.22.04~jammy` and Compose V2; holds Docker Engine packages at the installed version. |
| Application | Copies `compose.yml` and `.env` to `/opt/walmart`, pulls images, starts the `walmart` Compose project, and polls the health endpoint for `Online` (up to 10 attempts, 30 seconds apart). |
| Kiosk account and startup | Configures Windows Auto-Logon and the kiosk user's shell to launch fullscreen Edge using `C:\KioskApp\startup.html`; stores Edge profile data in `C:\KioskBrowserData`. Registers the `WSL Docker Startup` task to start the stack at Windows startup under the installing Administrator account. |
| 24/7 settings | Selects High Performance, disables sleep and hibernation, leaves disk timeouts off, disables USB selective suspend, applies the selected display timeout, and configures Windows Update not to auto-reboot while a user is logged on. |
---
The startup page checks `http://localhost:3000/api/v1/system/health-check/` and redirects to the application when the endpoint responds successfully.
## What `install.bat` Configures
## Maintenance
| 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. |
### Update the application
---
Run `C:\Apps\mini-pc-setup\scripts\update.bat` as Administrator, preferably after signing out of the kiosk account and into the Administrator account.
## Maintenance & Operations
The updater checks WSL and required files, syncs `compose.yml` and `.env` to `/opt/walmart`, prompts for Docker registry login, pulls images, and runs `docker compose -p walmart up -d --remove-orphans`. It then checks the health endpoint and prunes dangling images. The named Docker volumes are preserved, but containers may restart and the application may be temporarily unavailable during an update.
### Updating the Application (`scripts\update.bat`)
To change settings, edit `.env` or `compose.yml` in `C:\Apps\mini-pc-setup` before running the updater. The startup page is also copied to `C:\KioskApp` when present.
To update container images, `compose.yml`, `.env`, or `templates\startup.html` without losing database data:
### Commission the device
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.
Use [CheckList.md](./CheckList.md) to verify WSL/Docker, application health, kiosk startup, persistent browser data, peripherals, and power recovery.
### Uninstalling & Restoring Desktop (`scripts\uninstall.bat`)
### Uninstall or restore the desktop
Run **`C:\Apps\mini-pc-setup\scripts\uninstall.bat`** as Administrator and select a mode:
Run `C:\Apps\mini-pc-setup\scripts\uninstall.bat` as Administrator and choose 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.
- **`1` Auto Wipe All:** Requires typing `YES`. Removes kiosk settings and user/profile, browser data, kiosk files/tasks, and the Walmart Compose project and volumes; restores the Balanced power plan and removes selected policies. If run from `C:\Apps\mini-pc-setup`, it also schedules that setup folder for deletion.
- **`2` Manual / Custom:** Prompts whether to delete or restore the kiosk user's desktop, keep browser data, remove the Compose project, delete its volumes, and remove the setup folder.
---
Deleting Compose volumes permanently deletes local application/database data. The uninstaller removes the application stack and its project files; it does **not** uninstall the WSL distribution or Docker packages.
## 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:
- **The application is unavailable after reboot:** In Task Scheduler, inspect **WSL Docker Startup**. It should run at startup under the Administrator account used for installation (not `SYSTEM`). Check container status with:
wsl -d Ubuntu-22.04 -u root docker logs tv-backend-prod
```bat
wsl -d Ubuntu-22.04 -u root docker ps
```
- **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.
- **Inspect backend logs:**
```bat
wsl -d Ubuntu-22.04 -u root docker logs tv-backend-prod
```
- **Registry login or image pull fails:** Confirm Internet access, registry credentials, and the `FRONTEND_IMAGE` and `BACKEND_IMAGE` values in `.env`.
- **Leave kiosk mode for maintenance:** Press `Ctrl + Alt + Del` and switch/sign out to the Administrator account. The Administrator account retains the normal Windows desktop.