Complete early roadmap foundation and calendar helpers
This commit is contained in:
@@ -96,4 +96,6 @@ sudo RESTIC_PASSWORD_FILE=/root/.backup-secrets/agrarian-project-restic.password
|
||||
snapshots --tag agrarian-game --tag project
|
||||
```
|
||||
|
||||
Record restore tests in the handoff log with the snapshot name and result.
|
||||
Record restore tests in `Docs/Ops/BackupRestoreTestLog.md` with the snapshot
|
||||
name, restored path, result, and cleanup status. Summarize the latest result in
|
||||
handoff notes when useful.
|
||||
|
||||
@@ -89,3 +89,6 @@ qemu-img info vms/Ubuntu-Codex/disks/hdc-vdisk1.img.qcow2
|
||||
Restore should be done to a new VM or a test path first. Do not overwrite a
|
||||
working VM disk until the backup has been verified and the original disk has
|
||||
been preserved.
|
||||
|
||||
Record VM restore tests in `Docs/Ops/BackupRestoreTestLog.md` with the snapshot
|
||||
timestamp, checksum result, disk inspection result, and cleanup status.
|
||||
|
||||
@@ -0,0 +1,61 @@
|
||||
# Backup Restore Test Log
|
||||
|
||||
## Purpose
|
||||
|
||||
Backups are only useful if restore paths are tested before an emergency. This log records recurring restore tests for the Agrarian project backup and the development VM backups.
|
||||
|
||||
Use this file for the durable project record. Handoff notes can summarize the latest result, but the evidence and cadence live here.
|
||||
|
||||
## Cadence
|
||||
|
||||
- Weekly: restore one small file from the latest project snapshot to a temporary folder and verify it matches the live file.
|
||||
- Monthly: restore or inspect enough of the project repository snapshot to confirm Git metadata/history are usable.
|
||||
- Monthly: verify the latest VM backup snapshot is readable by checking `SHA256SUMS` and inspecting the backed-up disk metadata.
|
||||
- Quarterly: restore the project folder plus one VM definition/disk to a non-production test path.
|
||||
|
||||
## Evidence Required
|
||||
|
||||
Each entry should include:
|
||||
|
||||
- Date and local time.
|
||||
- Backup type: project, VM, or full drill.
|
||||
- Snapshot path, restic snapshot ID, or VM backup timestamp.
|
||||
- Command or runbook section used.
|
||||
- Result: Pass, Blocked, or Fail.
|
||||
- Notes on what was restored, where it was restored, and whether cleanup was completed.
|
||||
|
||||
## Log
|
||||
|
||||
| Date | Type | Snapshot | Result | Evidence / Notes |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 2026-05-15 | Project restore-test log setup | `/mnt/backups/linastorage/backups/agrarian-game/project/restic-repository` | Blocked | Log created. The expected restic repository path was not present on Ubuntu-Codex at setup time, so the first project restore test must run after the Linastorage backup mount/repository is confirmed. |
|
||||
| 2026-05-15 | VM restore-test log setup | `/mnt/user/backups/agrarian-game/vms/snapshots` | Blocked | Log created. The Unraid snapshot directory exists, but no VM snapshot directories were present at setup time. Run the first VM readability test after the next successful VM backup snapshot. |
|
||||
|
||||
## Project Restore Test Procedure
|
||||
|
||||
Use the project backup runbook for the authoritative paths:
|
||||
|
||||
```bash
|
||||
mkdir -p /tmp/agrarian-project-restore-test
|
||||
sudo sh -c 'RESTIC_PASSWORD_FILE=/root/.backup-secrets/agrarian-project-restic.password \
|
||||
restic -r /mnt/backups/linastorage/backups/agrarian-game/project/restic-repository \
|
||||
dump latest /mnt/projects/AgrarianGameBulid/AGRARIAN_DEVELOPMENT_ROADMAP.md \
|
||||
> /tmp/agrarian-project-restore-test/AGRARIAN_DEVELOPMENT_ROADMAP.md'
|
||||
diff -q /mnt/projects/AgrarianGameBulid/AGRARIAN_DEVELOPMENT_ROADMAP.md \
|
||||
/tmp/agrarian-project-restore-test/AGRARIAN_DEVELOPMENT_ROADMAP.md
|
||||
```
|
||||
|
||||
Record the restic snapshot ID, result, and cleanup status in the log table.
|
||||
|
||||
## VM Restore Test Procedure
|
||||
|
||||
Use the VM backup runbook for authoritative paths:
|
||||
|
||||
```bash
|
||||
cd /mnt/user/backups/agrarian-game/vms/snapshots/<timestamp>
|
||||
sha256sum -c SHA256SUMS
|
||||
qemu-img info vms/Ubuntu-Codex/disks/hdc-vdisk1.img.qcow2
|
||||
```
|
||||
|
||||
Record the VM snapshot timestamp, checksum result, disk metadata result, and cleanup status in the log table.
|
||||
|
||||
@@ -0,0 +1,78 @@
|
||||
# Agrarian Build Log Retention Policy
|
||||
|
||||
This policy covers generated build, package, cook, editor, crash, shader, and
|
||||
automation logs for the Agrarian Unreal project.
|
||||
|
||||
## Goals
|
||||
|
||||
- Keep enough recent logs to debug build and packaging failures.
|
||||
- Preserve important release/investor-demo logs long enough to explain what was
|
||||
shipped.
|
||||
- Prevent `Saved/`, `Builds/`, and generated automation output from growing
|
||||
without limit on the shared project drive.
|
||||
- Keep generated logs out of Git.
|
||||
|
||||
## Log Locations
|
||||
|
||||
- `Saved/BuildLogs/`: Windows editor builds, packaged target builds, and
|
||||
packaging logs.
|
||||
- `Saved/Logs/`: Unreal editor, cook, runtime, UnrealPak, World Partition, and
|
||||
commandlet logs.
|
||||
- `Saved/Crashes/`: editor/runtime crash context, logs, and dumps.
|
||||
- `Saved/MaterialStats/`: generated material stat CSV files.
|
||||
- `Saved/Shaders/` and `Saved/ShaderDebugInfo/`: generated shader diagnostics.
|
||||
- `Builds/`: packaged local build outputs. These are not retained as source
|
||||
artifacts unless explicitly published or sent externally.
|
||||
|
||||
## Default Retention
|
||||
|
||||
- Build/package logs in `Saved/BuildLogs/`: keep 90 days.
|
||||
- Unreal logs in `Saved/Logs/`: keep 30 days.
|
||||
- Crash reports in `Saved/Crashes/`: keep 90 days.
|
||||
- Material stats in `Saved/MaterialStats/`: keep 30 days.
|
||||
- Shader debug output in `Saved/Shaders/` and `Saved/ShaderDebugInfo/`: keep 14
|
||||
days.
|
||||
- Local packaged builds in `Builds/`: keep the latest published investor/demo
|
||||
package and any active test build; prune older regenerated builds manually.
|
||||
|
||||
## Preserve Before Pruning
|
||||
|
||||
Before deleting logs, preserve any file that is tied to:
|
||||
|
||||
- an investor/demo package;
|
||||
- a release candidate;
|
||||
- a crash or build failure still being investigated;
|
||||
- a bug report sent to another person;
|
||||
- a store upload or external test distribution.
|
||||
|
||||
Preserved logs should be copied to a dated folder under a local operational
|
||||
archive or attached to the related issue/release note before cleanup.
|
||||
|
||||
## Cleanup Script
|
||||
|
||||
Use:
|
||||
|
||||
```text
|
||||
Scripts/prune_build_logs.sh --dry-run
|
||||
Scripts/prune_build_logs.sh --apply
|
||||
```
|
||||
|
||||
The script is dry-run by default. It only removes generated files under known
|
||||
`Saved/` log/debug paths and empty directories left behind. It does not touch
|
||||
source, `Content/`, `Config/`, `Source/`, `Docs/`, or Git history.
|
||||
|
||||
## Cadence
|
||||
|
||||
- Run dry-run before major packaging cycles if the shared drive is getting full.
|
||||
- Run apply monthly during active development.
|
||||
- Always run dry-run first when preparing an investor or external test build.
|
||||
|
||||
## Git Policy
|
||||
|
||||
Generated logs are not committed. Commit only:
|
||||
|
||||
- build scripts;
|
||||
- packaging scripts;
|
||||
- retention policy docs;
|
||||
- release notes;
|
||||
- summaries of important failures or fixes.
|
||||
@@ -0,0 +1,179 @@
|
||||
# Development Infrastructure Recovery Runbook
|
||||
|
||||
## Purpose
|
||||
|
||||
This runbook gives a simple recovery path when the Agrarian development machines or shared project storage are unreachable. It covers:
|
||||
|
||||
- Unraid `DevBox`
|
||||
- `Ubuntu-Codex`
|
||||
- `Windows-Builder`
|
||||
- The `projects` SMB share
|
||||
|
||||
Use the least disruptive recovery path first. Do not reboot `DevBox` until VM-level and service-level checks have failed, because it hosts shared storage and the development VMs.
|
||||
|
||||
## Current Baseline
|
||||
|
||||
| System | Role | Address / Name | Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| `DevBox` | Unraid host, SMB storage, VM host | `192.168.5.8` / `DevBox` | Hosts `projects` share and VMs. |
|
||||
| `Ubuntu-Codex` | Source-control and automation VM | `192.168.5.10` expected, current host access may also show `192.168.5.6` or `192.168.5.9` depending on interface | Mounts `//192.168.5.8/projects` at `/mnt/projects`. |
|
||||
| `Windows-Builder` | Unreal/Visual Studio/GPU build VM | `192.168.5.12` | Uses fixed VirtIO MAC `52:54:00:17:ec:5d`. |
|
||||
| `projects` share | Shared Unreal project storage | `\\DevBox\projects` / `/mnt/projects` | Repo path is `/mnt/projects/AgrarianGameBulid`. |
|
||||
|
||||
## First Triage
|
||||
|
||||
From Ubuntu-Codex or another LAN machine:
|
||||
|
||||
```bash
|
||||
ping -c 3 192.168.5.8
|
||||
ping -c 3 192.168.5.12
|
||||
nc -vz -w 5 192.168.5.12 3389
|
||||
mount | rg '/mnt/projects|cifs|smb'
|
||||
```
|
||||
|
||||
From `DevBox`:
|
||||
|
||||
```bash
|
||||
virsh list --all
|
||||
virsh domiflist Windows-Builder
|
||||
virsh domiflist Ubuntu-Codex
|
||||
```
|
||||
|
||||
Expected VM NIC baselines:
|
||||
|
||||
- `Windows-Builder`: bridge `br0`, model `virtio-net`, MAC `52:54:00:17:ec:5d`
|
||||
- `Ubuntu-Codex`: bridge `br0`, model `virtio-net`, MAC `52:54:00:a5:cf:63`
|
||||
|
||||
## Safe Reboot Order
|
||||
|
||||
Use this order when multiple systems are unhealthy:
|
||||
|
||||
1. Save or stop active work where possible.
|
||||
2. Restart only the failing service if the host is reachable.
|
||||
3. Restart the affected VM from inside the guest if guest access works.
|
||||
4. Use `virsh shutdown <VM>` from `DevBox` if guest access does not work.
|
||||
5. Use `virsh reboot <VM>` only when a graceful shutdown is not enough.
|
||||
6. Use `virsh destroy <VM>` only when the VM is hung and no graceful path works.
|
||||
7. Reboot `DevBox` only after confirming SMB, libvirt, or host networking cannot be recovered individually.
|
||||
|
||||
Before planned VM shutdowns, consider a manual VM backup if the change is risky:
|
||||
|
||||
```bash
|
||||
/bin/bash /boot/config/custom/agrarian-vm-backup.sh --shutdown-running --vm Windows-Builder
|
||||
/bin/bash /boot/config/custom/agrarian-vm-backup.sh --shutdown-running --vm Ubuntu-Codex
|
||||
```
|
||||
|
||||
## Windows-Builder Recovery
|
||||
|
||||
Use these in order:
|
||||
|
||||
1. Confirm the VM is running:
|
||||
|
||||
```bash
|
||||
virsh domstate Windows-Builder
|
||||
virsh domiflist Windows-Builder
|
||||
```
|
||||
|
||||
2. Confirm RDP is listening from Ubuntu-Codex:
|
||||
|
||||
```bash
|
||||
nc -vz -w 5 192.168.5.12 3389
|
||||
```
|
||||
|
||||
3. Use the QEMU guest-agent path before relying on RDP when possible.
|
||||
4. If RDP is down but guest commands work, check:
|
||||
|
||||
```powershell
|
||||
Get-Service TermService
|
||||
Get-NetConnectionProfile
|
||||
Get-NetFirewallRule -DisplayGroup "Remote Desktop"
|
||||
```
|
||||
|
||||
5. Restart RDP only if it is not listening:
|
||||
|
||||
```powershell
|
||||
Restart-Service TermService -Force
|
||||
```
|
||||
|
||||
6. If Unreal visual inspection is needed, use Sunshine/Moonlight instead of RDP.
|
||||
|
||||
Detailed Windows-Builder references:
|
||||
|
||||
- `Docs/Ops/WindowsBuilderNetworkRdpStability.md`
|
||||
- `Docs/Ops/WindowsBuilderGpuRemoteAccess.md`
|
||||
|
||||
## Ubuntu-Codex Recovery
|
||||
|
||||
Use these in order:
|
||||
|
||||
1. Confirm VM state from `DevBox`:
|
||||
|
||||
```bash
|
||||
virsh domstate Ubuntu-Codex
|
||||
virsh domiflist Ubuntu-Codex
|
||||
```
|
||||
|
||||
2. Confirm SSH or console access.
|
||||
3. Confirm the project mount:
|
||||
|
||||
```bash
|
||||
mount | rg '/mnt/projects'
|
||||
ls -la /mnt/projects/AgrarianGameBulid
|
||||
```
|
||||
|
||||
4. If `/mnt/projects` is missing, remount the SMB share using the existing system mount configuration rather than creating a new ad hoc mount.
|
||||
5. Confirm Git access:
|
||||
|
||||
```bash
|
||||
git -C /mnt/projects/AgrarianGameBulid status --short
|
||||
git -C /mnt/projects/AgrarianGameBulid remote -v
|
||||
```
|
||||
|
||||
Do not wipe local changes to recover the VM. Preserve uncommitted work first with a commit, patch, or backup copy outside the repo.
|
||||
|
||||
## DevBox And SMB Recovery
|
||||
|
||||
Use these in order:
|
||||
|
||||
1. Confirm the host is reachable:
|
||||
|
||||
```bash
|
||||
ping -c 3 192.168.5.8
|
||||
```
|
||||
|
||||
2. Confirm Unraid services and VM state through the Unraid UI or SSH.
|
||||
3. Confirm the `projects` share is visible:
|
||||
|
||||
```bash
|
||||
smbclient -L //192.168.5.8 -N
|
||||
```
|
||||
|
||||
4. Confirm Ubuntu-Codex sees the share mounted:
|
||||
|
||||
```bash
|
||||
mount | rg '/mnt/projects'
|
||||
```
|
||||
|
||||
5. If DNS name `DevBox` fails but IP works, use the IP temporarily and repair the router/DNS record later.
|
||||
6. Avoid storing project files directly on the Unraid OS boot filesystem. Project data belongs on the `projects` share or in VMs.
|
||||
|
||||
## When To Stop And Inspect Before Rebooting
|
||||
|
||||
Pause before rebooting if:
|
||||
|
||||
- A build, package, backup, or VM disk copy is running.
|
||||
- Unreal Editor is open with unsaved assets.
|
||||
- Git has uncommitted changes that are not understood.
|
||||
- A backup or restore test is in progress.
|
||||
- DevBox has disk or array warnings.
|
||||
|
||||
## After Recovery
|
||||
|
||||
After any VM or `DevBox` recovery:
|
||||
|
||||
1. Confirm `/mnt/projects/AgrarianGameBulid` is reachable.
|
||||
2. Run `git status --short`.
|
||||
3. Confirm Windows-Builder RDP with `nc -vz -w 5 192.168.5.12 3389`.
|
||||
4. Confirm Sunshine only if visual inspection is needed.
|
||||
5. Record unusual recovery steps in the handoff notes or the relevant ops doc.
|
||||
|
||||
@@ -0,0 +1,86 @@
|
||||
# GitHub Branch Protection And Review Rules
|
||||
|
||||
## Current Repository State
|
||||
|
||||
- Repository: `pacificao/AgrarianGameBuild`
|
||||
- Visibility: private
|
||||
- Default branch: `main`
|
||||
- Current plan constraint: GitHub branch protection and repository rulesets are not enforceable on this private repository without GitHub Pro/Team or making the repository public.
|
||||
|
||||
GitHub API checks on 2026-05-15 returned the upgrade requirement for both branch protection and repository rulesets. To stay on the free tier, version 0.01 uses documented process controls and pull request templates now, with enforced protected `main` deferred to the later release/build pipeline milestone already tracked in the roadmap.
|
||||
|
||||
## Main Branch Policy
|
||||
|
||||
`main` is the only long-lived development branch for now.
|
||||
|
||||
Rules:
|
||||
|
||||
- Keep `main` buildable.
|
||||
- Prefer short-lived task branches for risky, multi-file, Unreal asset, infrastructure, or parallel work.
|
||||
- Direct commits to `main` are allowed only for small, scoped changes when validation is run and the working tree is understood.
|
||||
- Do not commit secrets, raw terrain source datasets, generated builds, `DerivedDataCache`, `Intermediate`, `Saved`, `Binaries`, large source-art archives, or local machine caches.
|
||||
- Before milestone demos or investor builds, confirm `main` is clean, pushed, and smoke-tested.
|
||||
|
||||
## Pull Request Rules
|
||||
|
||||
Use a pull request when any of these are true:
|
||||
|
||||
- The change touches gameplay systems, replication, persistence, build tooling, backup tooling, deployment, or server infrastructure.
|
||||
- The change modifies Unreal binary assets that are hard to review in text.
|
||||
- The change spans multiple roadmap items.
|
||||
- The change could affect packaged builds, dedicated servers, map tile delivery, or player data.
|
||||
- Another developer, workstation, or Codex session is working in the same area.
|
||||
|
||||
For PRs:
|
||||
|
||||
- Use the existing branch naming convention in `Docs/BranchingConventions.md`.
|
||||
- Link the roadmap item being completed.
|
||||
- Include validation steps actually run.
|
||||
- Include screenshots or build artifacts only as links or paths, not committed binaries.
|
||||
- Merge only after the change is reviewed or explicitly accepted by the project owner.
|
||||
|
||||
## Review Expectations
|
||||
|
||||
Minimum review expectations by change type:
|
||||
|
||||
| Change Type | Review Expectation |
|
||||
| --- | --- |
|
||||
| Docs-only | Self-review is acceptable if scoped and validated with `git diff --check`. |
|
||||
| Small code-only fix | Self-review is acceptable when tests/build checks pass and risk is low. |
|
||||
| Gameplay feature | Project owner review or second-developer review before merge when practical. |
|
||||
| Unreal binary assets | Record the editor action taken and visual/build validation performed. |
|
||||
| Build, backup, deployment, server, or GitHub workflow changes | Owner review before merge unless it is an emergency fix. |
|
||||
| Secrets, credentials, auth, payment, wallet, or production data handling | Do not merge without explicit owner review. |
|
||||
|
||||
## Required Local Checks Before Push
|
||||
|
||||
Run the checks appropriate for the change:
|
||||
|
||||
- Documentation/text changes: `git diff --check`
|
||||
- C++ changes: editor target build wrapper or Windows headless build command
|
||||
- Packaged-client changes: packaged client build wrapper and smoke test
|
||||
- Server changes: dedicated server build wrapper and relevant smoke test
|
||||
- Backup/tooling changes: dry-run mode first when available
|
||||
|
||||
Record skipped checks in the PR or commit message.
|
||||
|
||||
## Free-Tier Controls Installed Now
|
||||
|
||||
- `Docs/Ops/GitHubBranchProtectionAndReviewRules.md` defines the working policy.
|
||||
- `.github/PULL_REQUEST_TEMPLATE.md` gives a repeatable review checklist.
|
||||
- The roadmap keeps paid/private branch protection enforcement in the later release/build pipeline section.
|
||||
|
||||
## Future Enforced Settings
|
||||
|
||||
When a paid GitHub plan is justified or the repository becomes public, enable protected `main` with:
|
||||
|
||||
- Require pull request before merge.
|
||||
- Require at least one approving review for non-doc changes.
|
||||
- Dismiss stale approvals when new commits are pushed.
|
||||
- Require conversation resolution before merge.
|
||||
- Require status checks once CI exists.
|
||||
- Restrict force pushes.
|
||||
- Restrict branch deletion.
|
||||
- Require linear history if it does not interfere with Unreal asset workflows.
|
||||
- Allow administrators to bypass only for emergency recovery.
|
||||
|
||||
@@ -0,0 +1,62 @@
|
||||
# Windows-Builder GPU Remote Access
|
||||
|
||||
## Purpose
|
||||
|
||||
Windows-Builder needs two remote access paths:
|
||||
|
||||
- Headless build/control path for normal Codex work through QEMU guest tools and PowerShell.
|
||||
- Real-GPU visual path for occasional Unreal Editor inspection, startup screen checks, and gameplay verification.
|
||||
|
||||
RDP remains useful for administration, but it can interfere with the display session Unreal and GPU capture tools see. Use Sunshine/Moonlight when the goal is to inspect the GPU-rendered desktop.
|
||||
|
||||
## Current Setup
|
||||
|
||||
- Host VM: `Windows-Builder`
|
||||
- LAN address: `192.168.5.12`
|
||||
- GPU: NVIDIA GeForce GTX 1660 SUPER
|
||||
- GPU driver observed during setup: `32.0.15.9649`
|
||||
- Streaming host: Sunshine `2025.924.154138`
|
||||
- Virtual display: Virtual Display Driver by MTT, 1920x1080 at 60 Hz
|
||||
- Sunshine service: `SunshineService`, automatic startup
|
||||
- Sunshine web UI: `https://192.168.5.12:47990`
|
||||
- Login: use the Windows-Builder admin credential stored in the operational handoff, not a separate project password.
|
||||
|
||||
## Firewall Ports
|
||||
|
||||
Windows Firewall has LAN rules for Sunshine GameStream:
|
||||
|
||||
- TCP: `47984`, `47989`, `47990`, `48010`
|
||||
- UDP: `47998`, `47999`, `48000`, `48002`, `48010`
|
||||
|
||||
Keep these LAN-only. Do not expose Sunshine directly to the public internet.
|
||||
|
||||
## Client Workflow
|
||||
|
||||
1. Install Moonlight on the client machine used for visual inspection.
|
||||
2. Add host `192.168.5.12`.
|
||||
3. Pair with Sunshine when prompted.
|
||||
4. Launch Desktop from Moonlight.
|
||||
5. Use the GPU-streamed desktop for Unreal visual checks.
|
||||
|
||||
Codex should continue using the headless build/control path for normal code, cook, package, and commandlet work. Use Sunshine only when a visual inspection is actually needed.
|
||||
|
||||
## Verification
|
||||
|
||||
The setup was validated by:
|
||||
|
||||
- Confirming the GTX 1660 SUPER is present and healthy in Windows.
|
||||
- Confirming Sunshine is listening on its LAN ports.
|
||||
- Confirming the Sunshine web UI responds with HTTP 401 authentication from Ubuntu-Codex.
|
||||
- Confirming the virtual display is present as `Virtual Display Driver by MTT`.
|
||||
- Confirming Sunshine detects a 1920x1080 desktop and creates NVENC H.264/HEVC encoders on the GTX 1660 SUPER.
|
||||
|
||||
The GTX 1660 SUPER does not support AV1 NVENC. Sunshine may log an AV1 encoder failure during startup; this is expected and H.264/HEVC remain available.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- If Sunshine is unreachable, check `SunshineService`, Windows Firewall, and the VM IP address.
|
||||
- If Sunshine logs `failed to query display paths and modes`, verify the virtual display driver is installed and enabled.
|
||||
- If Moonlight shows a black screen after using RDP, disconnect RDP, restart `SunshineService`, and reconnect through Moonlight.
|
||||
- If controller input is required later, install and validate the ViGEmBus gamepad driver. It is not required for visual inspection.
|
||||
- If Unreal rendering differs under RDP, use Moonlight before changing graphics settings.
|
||||
|
||||
@@ -0,0 +1,84 @@
|
||||
# Windows-Builder Network And RDP Stability
|
||||
|
||||
## Purpose
|
||||
|
||||
Windows-Builder uses GPU passthrough for Unreal Editor and packaged build validation. GPU passthrough can make RDP and display behavior confusing because RDP, Sunshine, the virtual display driver, and the NVIDIA GPU are separate access paths.
|
||||
|
||||
This runbook records the stable baseline for normal administration and recovery.
|
||||
|
||||
## Stable Network Baseline
|
||||
|
||||
- VM: `Windows-Builder`
|
||||
- LAN IP: `192.168.5.12`
|
||||
- VM bridge: `br0`
|
||||
- NIC model: `virtio-net`
|
||||
- MAC address: `52:54:00:17:ec:5d`
|
||||
- Windows adapter: `Red Hat VirtIO Ethernet Adapter`
|
||||
- Windows adapter alias: `Ethernet`
|
||||
- Windows network profile: `Private`
|
||||
- DNS observed during stabilization: `192.168.4.1`
|
||||
|
||||
The fixed MAC address is important. Keep the VM NIC on the same bridge/MAC so router DHCP reservations, firewall rules, SMB mappings, RDP bookmarks, and Sunshine/Moonlight pairing continue to resolve to the same machine.
|
||||
|
||||
## Stable RDP Baseline
|
||||
|
||||
- RDP registry switch: enabled through `fDenyTSConnections = 0`
|
||||
- Service: `TermService`
|
||||
- Startup type: `Automatic`
|
||||
- Listener: TCP `3389`
|
||||
- Windows Firewall group: `Remote Desktop`
|
||||
- Required firewall rules:
|
||||
- `Remote Desktop - User Mode (TCP-In)`
|
||||
- `Remote Desktop - User Mode (UDP-In)`
|
||||
- `Remote Desktop - Shadow (TCP-In)`
|
||||
|
||||
Use RDP for administration, installs, and recovery. Use Sunshine/Moonlight for real-GPU visual inspection of Unreal because RDP can change the active display path seen by graphics applications.
|
||||
|
||||
## Power Baseline
|
||||
|
||||
The VM should not sleep while it is acting as the build host.
|
||||
|
||||
- Hibernate: off
|
||||
- AC sleep timeout: disabled
|
||||
- DC sleep timeout: disabled
|
||||
- AC monitor timeout: disabled
|
||||
- DC monitor timeout: disabled
|
||||
|
||||
This avoids the Windows kernel power standby events that can leave the VirtIO NIC disconnected until a manual wake or reconnect.
|
||||
|
||||
## Verification Commands
|
||||
|
||||
From Ubuntu-Codex:
|
||||
|
||||
```bash
|
||||
nc -vz -w 5 192.168.5.12 3389
|
||||
sshpass -p '<unraid-root-password>' ssh root@192.168.5.8 'virsh domiflist Windows-Builder'
|
||||
```
|
||||
|
||||
From Windows-Builder PowerShell:
|
||||
|
||||
```powershell
|
||||
Get-NetAdapter
|
||||
Get-NetConnectionProfile
|
||||
Get-Service TermService
|
||||
Get-NetFirewallRule -DisplayGroup "Remote Desktop"
|
||||
powercfg /a
|
||||
```
|
||||
|
||||
Expected results:
|
||||
|
||||
- `nc` reports that TCP `3389` succeeds.
|
||||
- `virsh domiflist` shows `bridge br0`, `virtio-net`, and MAC `52:54:00:17:ec:5d`.
|
||||
- `TermService` is running and automatic.
|
||||
- Remote Desktop firewall rules are enabled.
|
||||
- Hibernate is unavailable because it is disabled.
|
||||
|
||||
## Recovery Flow
|
||||
|
||||
1. Use the QEMU guest-agent path first if RDP fails.
|
||||
2. Confirm the VM still has IP `192.168.5.12`.
|
||||
3. Confirm the VM XML still has the fixed VirtIO NIC on `br0`.
|
||||
4. Confirm Windows still sees the network as `Private`.
|
||||
5. Restart `TermService` only if the service is not listening on TCP `3389`.
|
||||
6. If Unreal visual inspection is needed, use Sunshine/Moonlight instead of RDP.
|
||||
|
||||
Reference in New Issue
Block a user