partial backup

Author: JoeStech

content/learning-paths/servers-and-cloud-computing/dotnet-migration-nopcommerce/2-environment-setup.md

@@ -0,0 +1,74 @@
+---
+title: Environment setup
+weight: 2
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+Create two VMs in the same Azure region with matching OS and tooling so differences are attributable to architecture, not configuration drift.
+
+This path was validated with Ubuntu 24.04 LTS VMs in `westus2`:
+
+| | x86 | Arm |
+|---|---|---|
+| **VM size** | Standard_D2s_v6 | Standard_D2ps_v6 |
+| **vCPUs** | 2 | 2 |
+
+## Log in and create VMs
+
+```bash
+az login --use-device-code
+az account set --subscription <your-subscription>
+```
+
+Create both VMs in the same resource group and region.
+
+## Install tools on each VM
+
+```bash
+sudo apt-get update -y
+sudo apt-get install -y git curl jq ca-certificates gnupg docker.io
+sudo usermod -aG docker "$USER"
+
+sudo add-apt-repository ppa:dotnet/backports -y
+sudo apt-get update -y
+sudo apt-get install -y dotnet-sdk-9.0
+```
+
+Verify:
+
+```bash
+uname -m
+dotnet --version
+docker --version
+```
+
+Expected output: `x86_64` on the x86 VM, `aarch64` on the Arm VM. Both should report the same .NET SDK version (9.0.x).
+
+## PostgreSQL prerequisite for nopCommerce install
+
+nopCommerce migrations on PostgreSQL require the `citext` extension. Create it before running the installer:
+
+```bash
+docker run -d --name nop-postgres \
+  -e POSTGRES_USER=nop \
+  -e POSTGRES_PASSWORD=<password> \
+  -e POSTGRES_DB=nopcommerce \
+  -p 5432:5432 postgres:16
+
+docker exec nop-postgres psql -U nop -d nopcommerce \
+  -c "CREATE EXTENSION IF NOT EXISTS citext;"
+```
+
+## Optional: script-driven remote execution
+
+```bash
+az vm run-command invoke \
+  -g <resource-group> \
+  -n <vm-name> \
+  --command-id RunShellScript \
+  --scripts @./your-test-script.sh
+```
+
+This was used to run identical commands on both VMs.

content/learning-paths/servers-and-cloud-computing/dotnet-migration-nopcommerce/3-checkout-build-baseline.md

@@ -0,0 +1,91 @@
+---
+title: Build and baseline
+weight: 3
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+Pin nopCommerce to a reproducible release, build on both architectures, and capture a baseline that includes core storefront paths.
+
+## Clone and pin the source
+
+```bash
+git clone https://github.com/nopSolutions/nopCommerce.git
+cd nopCommerce
+git fetch --tags --prune
+git checkout release-4.90.3
+git rev-parse --short=10 HEAD   # expect 9beda11c42
+```
+
+## Restore and build
+
+```bash
+dotnet restore src/Presentation/Nop.Web/Nop.Web.csproj
+dotnet build src/Presentation/Nop.Web/Nop.Web.csproj -c Release --no-restore
+```
+
+## Start the application
+
+```bash
+cd src/Presentation/Nop.Web
+dotnet run -c Release --no-build --urls http://0.0.0.0:5000
+```
+
+## Baseline methodology
+
+Do not rely on `/install` alone. Baseline at least:
+
+- Home page
+- Search
+- Product page
+- Cart
+- Checkout
+
+Prerequisite: complete nopCommerce setup first (database configured and installer finished). Otherwise, storefront paths redirect to the install flow and do not represent real behavior.
+
+Use a valid product URL from your seeded catalog (for example, `/apple-macbook-pro`), not a hard-coded slug that may not exist in your dataset.
+
+Quick smoke probe (pre-install, useful as a connectivity check only):
+
+```bash
+for p in / \
+         '/search?q=book' \
+         '/apple-macbook-pro' \
+         '/cart' \
+         '/checkout'; do
+  echo "== $p =="
+  for i in $(seq 1 20); do
+    curl -sS -o /dev/null -w '%{time_total}\n' "http://127.0.0.1:5000$p"
+  done
+done
+```
+
+Before installation is complete, all storefront paths redirect to setup (`302`). Those numbers confirm reachability but are not valid performance baselines.
+
+## Installed-store endpoint baseline (validated)
+
+After fixing PostgreSQL setup (`citext`) and completing installation on both machines, the same endpoint benchmark was executed with `wrk` (`-t2 -c32 -d20s`) across this set:
+
+- `/`
+- `/search?q=book`
+- `/electronics`
+- `/apple-macbook-pro`
+- `/cart`
+- `/checkout`
+
+Storefront pages returned `200`; `/checkout` returned `302` (expected without an authenticated session).
+
+Requests/second comparison:
+
+| Endpoint | x86 | Arm | Arm vs x86 |
+|---|---:|---:|---:|
+| `/apple-macbook-pro` | 35.40 | 32.28 | -8.8% |
+| `/electronics` | 99.52 | 76.07 | -23.6% |
+| `/search?q=book` | 28.18 | 27.40 | -2.8% |
+
+Different endpoints show different gaps. Avoid reducing migration performance to a single number — use per-endpoint baselines to guide architecture-specific optimizations.
+
+## Arm MCP accelerator (optional)
+
+Use MCP to script repeated baseline runs and summarize deltas, but keep the manual baseline commands as your ground truth.

content/learning-paths/servers-and-cloud-computing/dotnet-migration-nopcommerce/4-dependency-mapping-manifests.md

@@ -0,0 +1,63 @@
+---
+title: Audit dependencies
+weight: 4
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+Use a manual-first audit, then use the Arm MCP server to accelerate checks.
+
+## Manual workflow (required)
+
+### 1. Map direct references
+
+```bash
+rg -n "<PackageReference|<ProjectReference" src
+```
+
+### 2. List transitive dependencies
+
+```bash
+dotnet list src/Presentation/Nop.Web/Nop.Web.csproj package --include-transitive
+```
+
+### 3. Generate an SBOM (required)
+
+```bash
+dotnet tool install --global CycloneDX
+dotnet CycloneDX src/Presentation/Nop.Web/Nop.Web.csproj -o sbom/
+```
+
+If tool installation is blocked, treat `dotnet list --include-transitive` plus `*.deps.json` evidence as a temporary fallback, not the final state.
+
+### 4. Inspect package internals for native payloads
+
+```bash
+mkdir -p /tmp/nupkg-audit
+cp ~/.nuget/packages/<package>/<version>/<package>.<version>.nupkg /tmp/nupkg-audit/
+cd /tmp/nupkg-audit
+unzip -l <package>.<version>.nupkg | rg "runtimes/|native/"
+```
+
+This is how you catch hidden architecture-specific binaries.
+
+## Dependency cascade rule
+
+Treat dependencies as a chain, not isolated items:
+
+- App depends on library A
+- Library A depends on library B
+- Library B is architecture-sensitive
+
+You must resolve B first, then validate A, then validate the app. In nopCommerce, `iTextSharp` and `System.Drawing` are an example of this chain.
+
+## Arm MCP accelerator (optional)
+
+After manual evidence is collected, use MCP tools to speed repetitive checks:
+
+- `knowledge_base_search` for package compatibility
+- `skopeo` or `check_image` for container image architecture coverage
+- `migrate_ease_scan` where scanner support exists
+
+Keep manual outputs as the source of truth. Use MCP to prioritize and scale, not to skip evidence.

content/learning-paths/servers-and-cloud-computing/dotnet-migration-nopcommerce/5-platform-code-deps.md

@@ -0,0 +1,81 @@
+---
+title: Replace platform-specific code
+weight: 5
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+Use one decision framework for every architecture-sensitive dependency.
+
+## Manual workflow (required)
+
+### 1. Find references
+
+```bash
+rg -n "System\.Drawing|ColorTranslator" src
+```
+
+### 2. Decide using the 4-option framework
+
+1. Keep it and test it deeply.
+2. Replace it with a managed cross-platform alternative.
+3. Replace it with a native equivalent that has feature parity.
+4. Remove the feature if business value is low.
+
+The workflow is the same for every dependency.
+
+### 3. Apply to nopCommerce
+
+- `System.Drawing` image paths: use option 2 with ImageSharp.
+- `iTextSharp` PDF color usage: start with option 1 (keep and test), then evaluate option 2 or 3 if you need full decoupling.
+
+```bash
+dotnet add src/Libraries/Nop.Services/Nop.Services.csproj package SixLabors.ImageSharp
+```
+
+## Baseline: exercise `System.Drawing.Common` first
+
+Before replacing code, run a direct image-operation baseline that uses `System.Drawing.Common` and `ImageSharp` on both x86 and Arm.
+
+Validated Azure results (150 resize+encode operations each) showed:
+
+- `System.Drawing.Common` lower average latency in this microbenchmark.
+- `ImageSharp` higher average latency in this microbenchmark.
+
+| Architecture | System.Drawing.Common avg (ms) | ImageSharp avg (ms) |
+|---|---:|---:|
+| x86 | 15.528 | 32.329 |
+| Arm | 15.941 | 70.512 |
+
+This does not invalidate the migration recommendation. Performance is only one dimension.
+
+## Why ImageSharp still improves the migration
+
+A second validated test removed `libgdiplus` on each VM:
+
+- With `libgdiplus` installed: both libraries succeeded.
+- Without `libgdiplus`: `System.Drawing.Common` failed (`TypeInitializationException`), ImageSharp still succeeded.
+
+`System.Drawing.Common` depends on `libgdiplus`, a native library that can break portability and behave inconsistently across platforms. ImageSharp is fully managed, so it runs identically on x86 and Arm Linux without native dependencies. For this migration, portability and predictable runtime behavior are the primary goals; then tune and benchmark ImageSharp paths as needed.
+
+### 4. Handle cascade dependencies
+
+Do not patch only the top-level project. If a transitive dependency is architecture-sensitive, fix it first, then retest consumers up the chain.
+
+## Arm MCP accelerator (optional)
+
+Use MCP to accelerate candidate discovery and compatibility research, then validate with manual tests:
+
+- `knowledge_base_search` for replacement candidates
+- `migrate_ease_scan` where supported
+
+## Upstream contribution path
+
+When you fix architecture issues in shared code, upstream the change.
+
+- Open a PR with Arm/x86 validation evidence.
+- Include benchmark and compatibility notes.
+- Track maintainer feedback and update migration docs with the final accepted approach.
+
+This has high leverage: each upstream fix reduces work for future migrations.

content/learning-paths/servers-and-cloud-computing/dotnet-migration-nopcommerce/6-containerization.md

@@ -0,0 +1,73 @@
+---
+title: Containerize the application
+weight: 6
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+Use a manual-first container workflow, then add MCP checks.
+
+## Manual workflow (required)
+
+### 1. Dockerfile path
+
+```bash
+docker build -f Dockerfile -t nop-web:dockerfile-test .
+```
+
+The nopCommerce Dockerfile uses `FROM --platform=$BUILDPLATFORM`, which is a BuildKit feature. The legacy Docker builder does not inject `$BUILDPLATFORM`, causing:
+
+```
+failed to parse platform : "" is an invalid OS component of ""
+```
+
+Fix by switching to buildx:
+
+```bash
+docker buildx create --use --name nopx || true
+docker buildx build --platform linux/amd64,linux/arm64 -t nop-web:multiarch --push .
+```
+
+If you cannot use buildx, create a simplified Dockerfile that removes the `--platform=$BUILDPLATFORM` argument and builds for the host architecture only.
+
+### 2. .NET SDK publish path (single architecture)
+
+```bash
+dotnet publish src/Presentation/Nop.Web/Nop.Web.csproj \
+  -c Release \
+  /t:PublishContainer \
+  -p:ContainerImageTag=publish-test
+```
+
+Validated outputs in this project:
+
+- x86 image: `591 MB`
+- Arm image: `623 MB`
+
+### 3. .NET SDK multi-arch path
+
+Define multi-arch runtime identifiers in the project file, then publish once.
+
+```xml
+<PropertyGroup>
+  <ContainerRuntimeIdentifiers>linux-x64;linux-arm64</ContainerRuntimeIdentifiers>
+</PropertyGroup>
+```
+
+```bash
+dotnet publish src/Presentation/Nop.Web/Nop.Web.csproj -c Release /t:PublishContainer
+```
+
+This is the scalable path for one image definition across both architectures.
+
+## Arm MCP accelerator (optional)
+
+Use MCP image tools after manual build succeeds:
+
+- `skopeo` to inspect manifest architecture coverage
+- `check_image` for a quick architecture report
+
+## Recommendation
+
+Use SDK publish as the default migration path. Keep Dockerfile for advanced layer control or custom build logic.