dohertj2/lmxopcua
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Doc — flesh out dev-environment.md inner-loop bootstrap with the explicit Windows install steps that surfaced when actually trying to stand up SQL Server on the local box: prereq winget commands per tool (.NET 10 SDK / .NET Framework 4.8 SDK + targeting pack / Git / PowerShell 7.4+); WSL2 install (UAC-elevated) as a separate sub-step before Docker Desktop; Docker Desktop install (UAC-elevated) followed by sign-out/sign-in for docker-users group membership; explicit post-install Docker Desktop config checklist (WSL 2 based engine = checked, Windows containers = NOT checked, WSL Integration enabled for Ubuntu) per decision #134; named volume otopcua-mssql-data:/var/opt/mssql on the SQL Server container so DB files survive container restart and docker rm; sqlcmd verification command using the new mssql-tools18 path that the 2022 image ships with; EF Core CLI install for use starting in Phase 1 Stream B; bumped step count from 8 → 10. Also adds a Troubleshooting subsection covering the seven most common Windows install snags (WSL distro not auto-installed needs -d Ubuntu; Docker PATH not refreshed needs new shell or sign-in; docker-users group membership needs sign-out/in; WSL 2 kernel update needs manual install on legacy systems; SA password complexity rules; Linux vs Windows containers mode mismatch; Hyper-V coexistence with Docker requires WSL 2 backend not Hyper-V backend per decision #134). Step 1 acceptance criteria gain "docker ps shows otopcua-mssql Up" and explicit note that steps 4a/4b need admin elevation (no silent admin-free path exists on Windows).

Browse Source 
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Joseph Doherty
2026-04-17 14:54:52 -04:00
parent 980ea5190c
commit bf6741ba7f
1 changed files with 97 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

106
docs/v2/dev-environment.md
View File

@@ -108,25 +108,102 @@ The tier split keeps developer onboarding fast (no Docker required for first bui
## Bootstrap Order — Inner-loop Developer Machine
Order matters because some installs have prerequisites. ~30–60 min total on a fresh machine.
Order matters because some installs have prerequisites and several need admin elevation (UAC). ~60–90 min total on a fresh Windows machine, including reboots.
**Admin elevation appears at**: WSL2 install (step 4a), Docker Desktop install (step 4b), and any `wsl --install -d` call. winget will prompt UAC interactively when these run; accept it. There is no fully-silent admin-free install path on Windows for Docker Desktop's prerequisites.
1. **Install .NET 10 SDK** (https://dotnet.microsoft.com/) — required to build anything
```powershell
winget install --id Microsoft.DotNet.SDK.10 --accept-package-agreements --accept-source-agreements
```
2. **Install .NET Framework 4.8 SDK + targeting pack** — only needed when starting Phase 2 (Galaxy.Host); skip for Phase 0–1 if not yet there
```powershell
winget install --id Microsoft.DotNet.Framework.DeveloperPack_4 --accept-package-agreements --accept-source-agreements
```
3. **Install Git + PowerShell 7.4+**
4. **Clone repos**:
```powershell
winget install --id Git.Git --accept-package-agreements --accept-source-agreements
winget install --id Microsoft.PowerShell --accept-package-agreements --accept-source-agreements
```
4. **Install Docker Desktop** (with WSL2 backend per decision #134, leaves Hyper-V free for the future TwinCAT XAR VM):
**4a. Enable WSL2** — UAC required:
```powershell
wsl --install
```
Reboot when prompted. After reboot, the default Ubuntu distro launches and asks for a username/password — set them (these are WSL-internal, not used for Docker auth).
Verify after reboot:
```powershell
wsl --status
wsl --list --verbose
```
Expected: `Default Version: 2`, at least one distro (typically `Ubuntu`) with `STATE Running` or `Stopped`.
**4b. Install Docker Desktop** — UAC required:
```powershell
winget install --id Docker.DockerDesktop --accept-package-agreements --accept-source-agreements
```
The installer adds you to the `docker-users` Windows group. **Sign out and back in** (or reboot) so the group membership takes effect.
**4c. Configure Docker Desktop** — open it once after sign-in:
- **Settings → General**: confirm "Use the WSL 2 based engine" is **checked** (decision #134 — coexists with future Hyper-V VMs)
- **Settings → General**: confirm "Use Windows containers" is **NOT checked** (we use Linux containers for `mcr.microsoft.com/mssql/server`, `oitc/modbus-server`, etc.)
- **Settings → Resources → WSL Integration**: enable for the default Ubuntu distro
- (Optional, large fleets) **Settings → Resources → Advanced**: bump CPU / RAM allocation if you have headroom
Verify:
```powershell
docker --version
docker ps
```
Expected: version reported, `docker ps` returns an empty table (no containers running yet, but the daemon is reachable).
5. **Clone repos**:
```powershell
git clone https://gitea.dohertylan.com/dohertj2/lmxopcua.git
git clone https://gitea.dohertylan.com/dohertj2/scadalink-design.git
git clone https://gitea.dohertylan.com/dohertj2/3yearplan.git
```
5. **Install SQL Server 2022 dev edition** (local install) OR start the Docker container (see Resource B):
6. **Start SQL Server** (Linux container; runs in the WSL2 backend):
```powershell
docker run --name otopcua-mssql -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=OtOpcUaDev_2026!" `
-p 1433:1433 -d mcr.microsoft.com/mssql/server:2022-latest
docker run --name otopcua-mssql `
-e "ACCEPT_EULA=Y" `
-e "MSSQL_SA_PASSWORD=OtOpcUaDev_2026!" `
-p 1433:1433 `
-v otopcua-mssql-data:/var/opt/mssql `
-d mcr.microsoft.com/mssql/server:2022-latest
```
6. **Install GLAuth** at `C:\publish\glauth\` per existing CLAUDE.md instructions; populate `glauth-otopcua.cfg` with the test users + groups (template in `docs/v2/dev-environment-glauth-config.md` — to be added in the setup task)
7. **Run `dotnet restore`** in the `lmxopcua` repo
8. **Run `dotnet build ZB.MOM.WW.OtOpcUa.slnx`** (post-Phase-0) or `ZB.MOM.WW.LmxOpcUa.slnx` (pre-Phase-0) — verifies the toolchain
The `-v otopcua-mssql-data:/var/opt/mssql` named volume preserves database files across container restarts and `docker rm` — drop it only if you want a strictly throwaway instance.
Verify:
```powershell
docker ps --filter name=otopcua-mssql
docker exec -it otopcua-mssql /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "OtOpcUaDev_2026!" -C -Q "SELECT @@VERSION"
```
Expected: container `STATUS Up`, `SELECT @@VERSION` returns `Microsoft SQL Server 2022 (...)`.
To stop / start later:
```powershell
docker stop otopcua-mssql
docker start otopcua-mssql
```
7. **Install GLAuth** at `C:\publish\glauth\` per existing CLAUDE.md instructions; populate `glauth-otopcua.cfg` with the test users + groups (template in `docs/v2/dev-environment-glauth-config.md` — to be added in the setup task)
8. **Install EF Core CLI** (used to apply migrations against the SQL Server container starting in Phase 1 Stream B):
```powershell
dotnet tool install --global dotnet-ef --version 10.0.*
```
9. **Run `dotnet restore`** in the `lmxopcua` repo
10. **Run `dotnet build ZB.MOM.WW.OtOpcUa.slnx`** (post-Phase-0) or `ZB.MOM.WW.LmxOpcUa.slnx` (pre-Phase-0) — verifies the toolchain
9. **Run `dotnet test`** with the inner-loop filter — should pass on a fresh machine
## Bootstrap Order — Integration Host
@@ -213,11 +290,22 @@ Seeds are idempotent (re-runnable) and gitignored where they contain credentials
### Step 1 — Inner-loop dev environment (each developer, ~1 day with documentation)
**Owner**: developer
**Prerequisite**: Bootstrap order steps 1–9 above
**Prerequisite**: Bootstrap order steps 1–10 above (note: steps 4a, 4b, and any later `wsl --install -d` call require admin elevation / UAC interaction — there is no fully-silent admin-free install path on Windows for Docker Desktop's prerequisites)
**Acceptance**:
- `dotnet test ZB.MOM.WW.OtOpcUa.slnx` passes
- A test that touches the central config DB succeeds (proves SQL Server reachable)
- A test that authenticates against GLAuth succeeds (proves LDAP reachable)
- `docker ps --filter name=otopcua-mssql` shows the SQL Server container `STATUS Up`
### Troubleshooting (common Windows install snags)
- **`wsl --install` says "Windows Subsystem for Linux has no installed distributions"** after first reboot — open a fresh PowerShell and run `wsl --install -d Ubuntu` (the `-d` form forces a distro install if the prereq-only install ran first).
- **Docker Desktop install completes but `docker --version` reports "command not found"** — `PATH` doesn't pick up the new Docker shims until a new shell is opened. Open a fresh PowerShell, or sign out/in, and retry.
- **`docker ps` reports "permission denied" or "Cannot connect to the Docker daemon"** — your user account isn't in the `docker-users` group yet. Sign out and back in (group membership is loaded at login). Verify with `whoami /groups | findstr docker-users`.
- **Docker Desktop refuses to start with "WSL 2 installation is incomplete"** — open the WSL2 kernel update from https://aka.ms/wsl2kernel, install, then restart Docker Desktop. (Modern `wsl --install` ships the kernel automatically; this is mostly a legacy problem.)
- **SQL Server container starts but immediately exits** — SA password complexity. The default `OtOpcUaDev_2026!` meets the requirement (≥8 chars, upper + lower + digit + symbol); if you change it, keep complexity. Check `docker logs otopcua-mssql` for the exact failure.
- **`docker run` fails with "image platform does not match host platform"** — your Docker is configured for Windows containers. Switch to Linux containers in Docker Desktop tray menu ("Switch to Linux containers"), or recheck Settings → General per step 4c.
- **Hyper-V conflict when later setting up TwinCAT XAR VM** — confirm Docker Desktop is on the **WSL 2 backend**, not Hyper-V backend. The two coexist only when Docker uses WSL 2.
### Step 2 — Integration host (one-time, ~1 week)