Published / updated29 Aug 2026

Developer Workstation Setup Lab

Before you start

You need: Articles 01–05, and a full-stack project to document.

Time: 4–6 hours, and a second person to test your documents.

Goal

Demonstrate that you can prepare a development environment from a clean machine and write a runbook another developer can follow without asking you anything.

Assignment

Two deliverables, both tested by someone else.

Deliverable	Contents
ENVIRONMENT.md	A checklist taking a clean machine to a working setup
RUNNING.md	How to run the full-stack School Management project

The test for both is the same: hand them to someone with a clean machine and watch them work through it without asking a question. Anything they have to ask is a missing line.

Part 1: Environment checklist

# Development Environment Setup

## Prerequisites
- Windows 11 / macOS 14 / Ubuntu 22.04
- 16 GB RAM recommended
- Administrator rights

## 1. .NET SDK
Install .NET 9 SDK from https://dotnet.microsoft.com/download

Verify:
    dotnet --version        # expect 9.x
    dotnet --list-sdks

## 2. Visual Studio 2022
Install with the workloads:
- ASP.NET and web development
- .NET desktop development
- Data storage and processing

## 3. VS Code
Install, then add:
- C# Dev Kit
- Python + Pylance
- ESLint, Prettier
- EditorConfig

Verify:
    code --version

## 4. SQL Server Developer + SSMS
Install SQL Server Developer edition.
- Authentication: **Mixed Mode**
- Note the instance name — default (.) or named (.\SQLEXPRESS)
Install SSMS separately.

Verify: connect and run
    SELECT @@SERVERNAME, @@VERSION, SUSER_SNAME();

## 5. Node.js
Install Node 20 LTS (or via nvm).

Verify:
    node --version          # expect v20.x
    npm --version

## 6. Python
Install Python 3.12. **On Windows, tick "Add python.exe to PATH".**

Verify:
    python --version        # python3 on macOS/Linux
    pip --version

## 7. Git
Install Git, then configure:
    git config --global user.name "Your Name"
    git config --global user.email "you@example.com"
    git config --global init.defaultBranch main
    git config --global core.autocrlf true     # Windows only

Verify:
    git --version
    git config --list

## 8. Postman
Install. Import the team collection and environment from /postman.

## 9. Development certificate
    dotnet dev-certs https --trust

Without this, HTTPS launch profiles fail with a certificate error.

## Verification
Run every command above. Every one must succeed before continuing.

Every step has a verify command. "Install Node" is not a step someone can confirm they completed; node --version returning v20.x is.

Name the exact versions. "Install .NET" leads to two developers on different SDKs and a build that works for one of them.

Two lines prevent the most common failures, and both are easy to omit:

• "Add python.exe to PATH" — without it, python is not recognised and every subsequent step fails confusingly.
• dotnet dev-certs https --trust — without it, the HTTPS profile fails in a way that looks like the application not starting.

core.autocrlf on Windows prevents a whole-file diff caused by line endings the first time a Windows developer commits to a repository created on Linux.

Part 2: The runbook

# Running the School Management System

Three parts run together: SQL Server, the ASP.NET Core API, and the frontend.

## 1. Database

    sqlcmd -S . -i database/01-schema.sql
    sqlcmd -S . -i database/02-seed.sql

Verify:
    sqlcmd -S . -d NexCodingSchool -Q "SELECT COUNT(*) FROM dbo.Student"
    -- expect 20

## 2. API

    cd src/NexCoding.SchoolPortal.Api
    dotnet user-secrets set "ConnectionStrings:SchoolDb" "Server=.;Database=NexCodingSchool;Integrated Security=True;TrustServerCertificate=True;"
    dotnet user-secrets set "Jwt:Key" "<any 32+ character string for local use>"
    dotnet restore
    dotnet watch run

Verify: open https://localhost:7099/swagger
Sign in with admin@nca.test / Password123! and call GET /api/students.

## 3. Frontend

    cd src/school-portal-web
    cp .env.example .env.development     # then set VITE_API_URL=https://localhost:7099
    npm ci
    npm run dev

Verify: open http://localhost:5173, sign in, and see the student list.

## Ports
| Service  | Port |
|----------|------|
| API      | 7099 (https), 5099 (http) |
| Frontend | 5173 |
| SQL      | 1433 |

## Troubleshooting
See TROUBLESHOOTING.md.

npm ci, not npm install. It installs exactly what the lock file specifies, so a new developer gets the same versions as everyone else.

Secrets go in user secrets, not appsettings.json. The runbook tells the developer to set them; it never contains real values, because it is committed.

Every step has a verification. "Run the API" is not enough — "open Swagger and call GET /api/students" confirms the database connection, the JWT configuration and the endpoint in one action.

The port table exists because port conflicts are the most common local failure, and knowing what should be on 7099 makes the conflict diagnosable in seconds.

Part 3: Troubleshooting

# Troubleshooting

## dotnet: command not found
The SDK is not installed or not on PATH. Reinstall and reopen the terminal —
a new PATH entry does not reach an already-open terminal.

## Cannot connect to SQL Server
1. Is the service running?          services.msc → SQL Server (MSSQLSERVER)
2. Is the instance name right?      Named instances need .\SQLEXPRESS
3. Is TCP/IP enabled?               SQL Server Configuration Manager
4. Is the login valid?              SELECT SUSER_SNAME();

Error numbers:
| 2 / 53 | Server not found — instance name or firewall |
| 18456  | Login failed — credentials or missing login |
| 4060   | Cannot open database — name or permission |

## HTTPS certificate error
    dotnet dev-certs https --clean
    dotnet dev-certs https --trust

## Port already in use
    netstat -ano | findstr :7099        # Windows
    lsof -i :7099                        # macOS/Linux
Then stop that process, or change the port in launchSettings.json.

## Python: module not found in VS Code only
The wrong interpreter is selected.
Ctrl+Shift+P → Python: Select Interpreter → choose the one in .venv

## npm: cannot find module
    rm -rf node_modules package-lock.json
    npm install
Last resort — read the error first.

## CORS error in the browser
Not fixable in the frontend. The API must allow the frontend's origin.
Check Program.cs: UseCors after UseRouting, before UseAuthentication.

## 401 on every API call
Token missing or expired. Check Application → localStorage in DevTools,
and decode the token at jwt.io to read the exp claim.

A troubleshooting document is the highest-value part of a runbook, because it is written from problems that actually happened. Add to it every time someone gets stuck.

Two entries are worth their place on their own: the SQL error-number table turns "cannot connect" into a specific cause, and the CORS entry stops the next developer spending a morning trying to fix it in JavaScript.

Part 4: Verifying the environment

# verify-environment.ps1
$checks = @(
    @{ Name = ".NET SDK";  Command = "dotnet --version";  Expected = "9." }
    @{ Name = "Node";      Command = "node --version";    Expected = "v20" }
    @{ Name = "npm";       Command = "npm --version";     Expected = "" }
    @{ Name = "Python";    Command = "python --version";  Expected = "3.1" }
    @{ Name = "Git";       Command = "git --version";     Expected = "" }
)

$failed = $false

foreach ($check in $checks) {
    try {
        $output = Invoke-Expression $check.Command 2>&1 | Out-String

        if ($check.Expected -and $output -notmatch [regex]::Escape($check.Expected)) {
            Write-Host "WRONG VERSION  $($check.Name): $($output.Trim())" -ForegroundColor Yellow
            $failed = $true
        } else {
            Write-Host "OK             $($check.Name): $($output.Trim())" -ForegroundColor Green
        }
    } catch {
        Write-Host "MISSING        $($check.Name)" -ForegroundColor Red
        $failed = $true
    }
}

if ($failed) { exit 1 }

A script beats a checklist because it cannot be skimmed. It reports every problem at once rather than one per attempt, and it can run in CI to catch a version drift on the build server.

Distinguishing "missing" from "wrong version" matters — they have different fixes, and a wrong version is the harder one to notice.

Submission template

ENVIRONMENT.md
  Every tool, exact version, install source:
  A verify command for each:
  Post-install configuration (PATH, certificates, git config):

RUNNING.md
  Prerequisites:
  Numbered steps, database → API → frontend:
  A verification after each step:
  Port table:
  Where secrets come from, and how to set them:

TROUBLESHOOTING.md
  Every problem encountered during setup:
  Symptom → cause → fix:
  Error-number tables where they apply:

verify-environment script

Evidence
  Who tested it, on what machine:
  Every question they had to ask:
  What you changed as a result:

Verification

The clean-machine test. Give the documents to someone with a fresh machine — or use a VM — and watch. Every question they ask is a defect in the document. Note it, fix it, and test again.

Time it. A working environment should take under an hour from a clean machine. Longer usually means missing prerequisites or steps in the wrong order.

Every command runs as written. Copy each one from the document into a terminal. A command that needs editing before it works is not a step.

Every verification actually verifies. "Run the API" is not a check. "Open Swagger and call GET /api/students" confirms three things at once.

No secret in any document. They are committed. git log -p | grep -i "password\|token\|connectionstring" must return nothing.

The troubleshooting document covers what actually happened. If your tester hit a problem not listed, add it.

The verify script exits non-zero on failure, so it can gate a CI job.

AI practice

Two AI exercises from this track's syllabus. Do both after the documents are tested, and apply Track 18's discipline — every answer is a hypothesis until you have run it.

1. Ask AI to explain a tool error message. Take three real errors from your setup — SQL Server error 18456, a dotnet command not found, an npm peer-dependency failure — and ask what each means and what to check. Verify each answer against the actual cause you found. Then add whichever explanations were right to TROUBLESHOOTING.md.
2. Use AI to create a runbook, then verify every command. Ask for setup instructions for a .NET plus React plus SQL Server project, then run every single command as written. Note which need editing, which are for the wrong operating system, and which reference versions that do not exist. A command that needs editing before it works is not a step — and that gap is exactly what the clean-machine test measures.

Exercise 2 is the calibration one. Generated runbooks look complete and usually omit dotnet dev-certs https --trust and the "Add python.exe to PATH" checkbox — the two lines that cause the most confusing failures.

Track 18 — Reviewing AI-generated code — has the full checklist.

Self-assessment

Your submission is complete when someone with a clean machine can reach a running full-stack application using only your documents.

Four specific tests of quality:

• Does every install step have a verify command? "Install Node" is not something a reader can confirm they did correctly.
• Are versions pinned? "Install .NET" produces two developers on different SDKs and a build that works for one.
• Does the troubleshooting document contain real problems? A generic one is worthless; one written from a genuine setup is the most-used file in a repository.
• Did your tester ask any questions? Each one is a missing line, and fixing them is the exercise.

Track completion criteria

You can use core development tools comfortably, build and debug projects, test APIs, inspect browser failures, and treat npm as frontend tooling rather than a taught backend.

Specifically, you can:

• Open an unfamiliar solution, build it, and navigate it by keyboard
• Debug with breakpoints, conditional breakpoints, Watch and the Call Stack
• Configure VS Code so a repository gives a new developer a working setup
• Connect to SQL Server, explore a database, and run queries without risking data
• Read an execution plan and compare logical reads
• Build a Postman collection with environments, tokens and tests
• Use Swagger to explore an API and document your own correctly
• Diagnose a frontend failure from Network, Console and Application
• Decide from a status code whether a problem is frontend or backend
• Run a Node-based build reproducibly with npm ci and a committed lock file
• Write documentation another developer can follow without asking questions

The syllabus recommends Track 17 — Debugging Skills or Track 16 — Git & Source Control next.