98 lines
8.2 KiB
Markdown
98 lines
8.2 KiB
Markdown
# DTS Torque Vault — Mini PC Kiosk Deployment
|
|
|
|
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
|
|
|
|
```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
|
|
```
|
|
|
|
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
|
|
|
|
- 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.
|
|
|
|
## 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.
|
|
|
|
## What the installer configures
|
|
|
|
| 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.
|
|
|
|
## Maintenance
|
|
|
|
### 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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
### Commission the device
|
|
|
|
Use [CheckList.md](./CheckList.md) to verify WSL/Docker, application health, kiosk startup, persistent browser data, peripherals, and power recovery.
|
|
|
|
### Uninstall or restore the desktop
|
|
|
|
Run `C:\Apps\mini-pc-setup\scripts\uninstall.bat` as Administrator and choose a mode:
|
|
|
|
- **`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
|
|
|
|
- **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:
|
|
|
|
```bat
|
|
wsl -d Ubuntu-22.04 -u root docker ps
|
|
```
|
|
|
|
- **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.
|