Breakthrough change
This commit is contained in:
@@ -1,41 +1,93 @@
|
||||
# Setup Project on Mini PC (Windows)
|
||||
# DTS Torque Vault — Mini PC Kiosk Deployment & Maintenance Guide (24/7)
|
||||
|
||||
In the `scripts` folder there are several `.bat` files used to set up the environment on the mini PC.
|
||||
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.
|
||||
|
||||
## Requirements
|
||||
---
|
||||
|
||||
- Create an `Apps` folder on the `C` drive.
|
||||
- Clone this repository into the `Apps` directory. Note that should not rename the directory you have just cloned.
|
||||
## 1. Repository & Deployment Structure
|
||||
|
||||
## Steps
|
||||
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
|
||||
|
||||
1. **Update and rename `.env.template` file to `.env`**
|
||||
> **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.
|
||||
|
||||
2. **Run `setup-wsl.bat`**
|
||||
- This will install WSL with Ubuntu‑22.04.
|
||||
- Follow the prompts to create a default UNIX user account inside WSL.
|
||||
---
|
||||
|
||||
3. **Run `setup-docker.bat`**
|
||||
- This will install Docker Engine (v2) and Docker Compose V2 inside the Ubuntu WSL you just created.
|
||||
- It also enables the Docker daemon to start automatically.
|
||||
## 2. Fresh Mini PC Installation
|
||||
|
||||
4. **Run `setup-prj.bat`**
|
||||
- Login docker to Gitea.
|
||||
- Create `walmart` folder in WSL.
|
||||
- Copy `.env` and `compose` files to `walmart` folder.
|
||||
- Run docker compose file `docker compose up -d`.
|
||||
### Option A: 1-Click Deployment via Gitea Latest Release _(Recommended)_
|
||||
|
||||
5. **Run `update-prj.bat`**
|
||||
- This will pull latest image from container registry.
|
||||
- Restart all containers in compose file
|
||||
- Remove unused images (old images)
|
||||
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`.
|
||||
|
||||
## Notes
|
||||
### Option B: Manual Deployment from `C:\Apps\mini-pc-setup\`
|
||||
|
||||
- During these steps, you may be asked to enter your UNIX user password (for `sudo` commands).
|
||||
- Make sure you reboot your PC after running `setup-wsl.bat` before continuing with the next scripts.
|
||||
- Verify installation by running:
|
||||
```bash
|
||||
docker --version
|
||||
docker compose version
|
||||
```
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## 3. Switching to Administrator for Maintenance
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## 4. Updating the Application (`scripts\update.bat`)
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## 5. Uninstalling / Restoring Normal Windows Mode (`scripts\uninstall.bat`)
|
||||
|
||||
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**.
|
||||
|
||||
---
|
||||
|
||||
## 6. Quick 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**. |
|
||||
|
||||
Reference in New Issue
Block a user