Filip Zubik
c42943cfa8
Initial deployment suite for X9.cz MSP Windows 10/11 deployment: - PowerShell scripts 00-11: admin account, bloatware removal, software (winget+Atera), system registry tweaks, default profile, personalization, scheduled tasks, BackInfo desktop info, Windows activation, PC identity/rename, network, Dell Update - Web platform: xetup.x9.cz (nginx), spec/annotation page, /dl shortlink, GitHub mirror - Forgejo Actions CI: auto-build xetup.exe on push, publish to releases/latest - Go xetup.exe: embeds all scripts/assets, per-feature checkboxes, load/save config
175 lines
7 KiB
Markdown
175 lines
7 KiB
Markdown
# CLAUDE.md - Instructions for Claude Code
|
|
|
|
## Project context
|
|
|
|
MSP deployment script for X9.cz - automated preparation of new Windows 10/11 computers for clients.
|
|
Replaces ~3 hours of manual setup with a single PowerShell script (evolving toward Go TUI launcher).
|
|
|
|
**Key parameters:**
|
|
- Target OS: Windows 10 and Windows 11 (x64), including unsupported HW
|
|
- Execution: as Administrator on already-installed Windows (not WinPE/autounattend)
|
|
- Volume: ~20 machines per month, various clients
|
|
- Operator: MSP technician on-site at client
|
|
|
|
---
|
|
|
|
## Communication
|
|
|
|
- Communicate with the user in Czech
|
|
- Code, comments, log messages: English only (no diacritics rule still applies)
|
|
|
|
---
|
|
|
|
## Repo structure
|
|
|
|
```
|
|
windows-deployment-new/
|
|
├── CLAUDE.md <- this file
|
|
├── SPEC.md <- technical specification
|
|
├── Deploy-Windows.ps1 <- master script (entry point)
|
|
├── scripts/
|
|
│ ├── 00-admin-account.ps1 <- create hidden admin account
|
|
│ ├── 01-bloatware.ps1 <- remove AppX, Capabilities, Features
|
|
│ ├── 02-software.ps1 <- winget installs + Adobe PDF default
|
|
│ ├── 03-system-registry.ps1 <- HKLM tweaks
|
|
│ ├── 04-default-profile.ps1 <- C:\Users\Default\NTUSER.DAT changes
|
|
│ ├── 05-personalization.ps1 <- colors, wallpaper, theme
|
|
│ ├── 06-scheduled-tasks.ps1 <- register scheduled tasks
|
|
│ ├── 07-desktop-info.ps1 <- TO BE DELETED (replaced by BackInfo)
|
|
│ └── 08-activation.ps1 <- Windows activation via slmgr
|
|
├── config/
|
|
│ └── config.json <- per-client config
|
|
├── assets/
|
|
│ ├── Backinfo/ <- BackInfo.exe + .ini + backinfo_W11.ps1
|
|
│ └── Logo/ <- X9-ikona.ico, X9-logo.jpeg
|
|
└── tests/
|
|
└── Test-Deployment.ps1 <- post-deployment verification
|
|
```
|
|
|
|
---
|
|
|
|
## Conventions and rules
|
|
|
|
### PowerShell
|
|
- Always `#Requires -RunAsAdministrator` in master script
|
|
- `$ErrorActionPreference = "Continue"` - script must survive partial failures
|
|
- Log every step to `C:\Windows\Setup\Scripts\Deploy.log`
|
|
- Logging via `Write-Log` function defined in master script
|
|
- `Invoke-Step` function wraps every step - catches errors, logs, continues
|
|
- Comments in English, code in English
|
|
- NO diacritics - no accented characters anywhere: not in comments, not in user messages, not in log output
|
|
- NO emoticons - not in comments, not in output messages
|
|
- Reason: encoding issues across systems, log readability, compatibility
|
|
|
|
### Master script structure
|
|
```powershell
|
|
# 1. Load config.json
|
|
# 2. Run individual scripts in order
|
|
# 3. Print summary report at end (OK/ERROR counts)
|
|
```
|
|
|
|
### Master script switches
|
|
| Switch | Behavior |
|
|
|---|---|
|
|
| `-SkipBloatware` | Skip step 1 |
|
|
| `-SkipSoftware` | Skip step 2 |
|
|
| `-SkipDefaultProfile` | Skip step 4 |
|
|
| `-DryRun` | Run without changes, log only |
|
|
|
|
### Testing
|
|
- Test VM: Windows 10/11 x64 on VMware ESXi (X9.cz internal infrastructure)
|
|
- Before each test: take snapshot
|
|
- After test: revert snapshot
|
|
- Dev environment: x64 VM only - NOT ARM (no Parallels/Apple Silicon for testing)
|
|
|
|
---
|
|
|
|
## Important notes
|
|
|
|
### BackInfo (replaces custom DesktopInfo)
|
|
BackInfo.exe IS used. Located in assets/Backinfo/. Deployment:
|
|
1. Copy assets/Backinfo/ to C:\Program Files\Backinfo\
|
|
2. Run backinfo_W11.ps1 (detects OS, writes registry, creates Startup shortcut)
|
|
3. BackInfo.exe auto-starts on every logon, reads INI, renders BMP with system info
|
|
- Configurable via BackInfo.ini (fonts, positions, data sources)
|
|
- Displays: hostname (centered, large), username, OS, HW info, network info
|
|
- DELETE 07-desktop-info.ps1 - no longer needed
|
|
|
|
### Adobe Reader as default PDF app
|
|
- After install: set .pdf -> AcroRd32 association
|
|
- Scheduled task PDF-DefaultApp restores association on every logon (guard against Edge overwriting it)
|
|
- NOTE: UCPD.sys (kernel driver since Feb 2024) blocks UserChoice writes. Consider disabling UCPD during deployment.
|
|
|
|
### Default Profile
|
|
- Changes to C:\Users\Default\NTUSER.DAT via reg load / reg unload
|
|
- Applies to all new users - critical for MSP deployment
|
|
- Currently logged-in user gets changes via direct write to HKCU
|
|
|
|
### Winget
|
|
- Always use --accept-package-agreements --accept-source-agreements
|
|
- Check winget availability before running installs
|
|
- Log result of every install
|
|
|
|
### Atera Agent
|
|
- Download: `Invoke-WebRequest -Uri "https://x9.servicedesk.atera.com/api/utils/agent-install/windows/?cid=31&aeid=50b72e7113e54a63ac76b96c54c7e337" -OutFile setup.msi`
|
|
- Install: `msiexec /i setup.msi /qn`
|
|
|
|
### Admin account (adminx9)
|
|
- NO PASSWORD (changed from previous version)
|
|
- FullName = "X9.cz s.r.o." (via ADSI)
|
|
- Hidden from login screen
|
|
- Added to Administrators group
|
|
|
|
---
|
|
|
|
## DO NOT
|
|
|
|
- Do not use $ErrorActionPreference = "Stop" - script must survive partial failure
|
|
- Do not remove Calculator (Microsoft.WindowsCalculator) - intentionally kept
|
|
- Do not use ARM VM for testing
|
|
- Do not write scripts depending on specific username - script is universal
|
|
- Do not use hardcoded paths that do not exist on clean Windows
|
|
- NO diacritics - no accented characters in any part of any script
|
|
- NO emoticons - none in comments, log messages or output
|
|
- Do not remove OneDrive - must remain installable for M365
|
|
- Do not remove RDP/RDS - must remain functional
|
|
- Do not remove Microsoft-RemoteDesktopConnection from Optional Features
|
|
|
|
---
|
|
|
|
## Planned changes (from review v2, 2026-04-15)
|
|
|
|
### Must fix
|
|
- [ ] Remove OneDrive uninstall from 03-system-registry.ps1 and 04-default-profile.ps1
|
|
- [ ] Remove password from admin account, add FullName = "X9.cz s.r.o."
|
|
- [ ] Delete 07-desktop-info.ps1, replace with BackInfo deployment step
|
|
- [ ] Add powercfg settings (standby-timeout-ac 0, monitor-timeout-ac 60, etc.)
|
|
- [ ] Add proxy auto-detect disable (AutoDetect = 0)
|
|
- [ ] Add Atera Agent install step
|
|
- [ ] Extend Edge policies (~15 more keys)
|
|
|
|
### New features (from colleague spec v2)
|
|
- [ ] Taskbar pinned apps: admin vs user variants via XML layout + -ProfileType parameter
|
|
- [ ] Explorer: ShowRecent=0, ShowFrequent=0, FullPath=1 in CabinetState
|
|
- [ ] Network discovery: enable ping, set private network profile (post-restart step)
|
|
- [ ] PC rename: Rename-Computer as final step before restart
|
|
- [ ] C:\X9 directory structure with custom folder icon
|
|
|
|
### Architecture evolution
|
|
- [ ] Go TUI launcher (xetup.exe) embedding PS scripts
|
|
- [ ] spec.yaml as single source of truth
|
|
- [ ] Web platform at xetup.x9.cz (Forgejo + docs + comments)
|
|
- [ ] Self-update mechanism in xetup.exe
|
|
|
|
---
|
|
|
|
## Open questions
|
|
|
|
| # | Question | Status |
|
|
|---|---|---|
|
|
| 1 | BackInfo replacement | DONE - using BackInfo.exe from assets/ |
|
|
| 2 | Complete SW list for winget | TODO - list incomplete |
|
|
| 3 | Per-client variability via config.json | FUTURE |
|
|
| 4 | Admin account adminx9 | DECIDED - no password, FullName "X9.cz s.r.o." |
|
|
| 5 | UCPD driver workaround for PDF default | TODO - disable during deployment |
|
|
| 6 | Atera MFA bypass | OPEN - does aeid parameter avoid MFA? |
|