<# .SYNOPSIS Turnkey ShopDB developer-workstation bootstrap for Windows. .DESCRIPTION Stands up a ShopDB stack from a git branch on a fresh dev box with as few manual steps as possible: 1. Checks the tools a dev needs (git, Docker) and offers to install any that are missing via winget (with a prompt - nothing is installed silently). Python is optional and only checked when -CheckPython is passed, because the app itself runs entirely in the container. 2. Picks a channel: stable -> pulls the 'stable' image (built from main), no DEV badge. edge -> pulls the 'edge' image (built from main), red DEV badge. The two channels use different compose project names, host ports, and named volumes, so they run side by side without colliding. 3. Generates a .env for the channel (dev-grade secrets, NOT for production) if one does not already exist, then PULLS the prebuilt channel image from GHCR and brings up the stack. Nothing is built on the host: the image is produced by CI, so a pilot needs only Docker (no Node/npm and no source compile behind the corporate proxy). Windows-only by design: pre-release audience is Windows. Not a production installer - see deploy/windows/installer/shopdb-install.ps1 for that. .PARAMETER Channel 'stable' (the newest release tag) or 'edge' (main, the trunk). Defaults to 'stable'. .PARAMETER Ref Override the git ref to build. Defaults to the newest v* tag for stable, 'main' for edge. Retained for compatibility; the pull flow selects the image by channel tag, so this now only affects which branch the working tree is prepared on. .PARAMETER CheckPython Also verify a local Python 3.11+ (only needed if you run tests/tooling on the host rather than in the container). .PARAMETER SkipDependencyInstall Report missing dependencies and stop instead of offering winget installs. Handy for CI-style dry runs. .EXAMPLE ./scripts/dev-bootstrap.ps1 -Channel edge .NOTES ASCII only, no emoji or smart punctuation, per repo style. PowerShell 5.1+. #> [CmdletBinding()] param( [ValidateSet('stable', 'edge')] [string]$Channel = 'stable', [string]$Ref, [switch]$CheckPython, [switch]$SkipDependencyInstall ) Set-StrictMode -Version Latest $ErrorActionPreference = 'Stop' # Channel -> (branch, compose project, host ports, badge label). Kept in one # table so adding a channel later is a single edit. Ports are offset for edge so # both stacks bind distinct host ports; the container-internal ports never move. $channels = @{ stable = @{ Ref = 'main' Project = 'shopdb-stable' ApiPort = 5001 MysqlPort = 3306 EnvLabel = '' ImageTag = 'stable' } edge = @{ Ref = 'main' Project = 'shopdb-edge' ApiPort = 5011 MysqlPort = 3316 EnvLabel = 'DEV' ImageTag = 'edge' } } # GHCR repository that CI (.github/workflows/publish-images.yml) publishes the # per-channel images to. Pilots PULL this instead of building from source, # because building behind an inspecting proxy is unreliable. $imageRepo = 'ghcr.io/ge-aero/shopdb-flask' function Write-Step { param([string]$Message) Write-Host '' Write-Host "==> $Message" -ForegroundColor Cyan } function Write-Ok { param([string]$Message) Write-Host " OK: $Message" -ForegroundColor Green } function Write-Warn { param([string]$Message) Write-Host " WARN: $Message" -ForegroundColor Yellow } function Test-Command { param([string]$Name) return [bool](Get-Command $Name -ErrorAction SilentlyContinue) } # Detect a corporate TLS-inspection root CA (e.g. Zscaler) by inspecting the # certificate chain the host uses to reach the npm registry, then stage it as # corp-root-ca.pem in the build context so the Docker frontend build can trust # it. On a clean network this simply stages a public root, which is harmless. # Writes nothing and returns quietly when detection is not possible. function Set-CorpRootCa { param( [Parameter(Mandatory)][string]$RepoRoot ) $certPath = Join-Path $RepoRoot 'corp-root-ca.pem' try { $request = [System.Net.HttpWebRequest]::Create('https://registry.npmjs.org/') $request.Method = 'HEAD' $request.Timeout = 10000 try { $response = $request.GetResponse(); $response.Close() } catch { } $cert = $request.ServicePoint.Certificate if (-not $cert) { Write-Warn 'Could not read the TLS certificate chain; skipping corp CA staging.' return } $chain = New-Object System.Security.Cryptography.X509Certificates.X509Chain $chain.ChainPolicy.RevocationMode = 'NoCheck' $cert2 = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($cert) [void]$chain.Build($cert2) $root = $chain.ChainElements[$chain.ChainElements.Count - 1].Certificate $issuer = $root.Subject $builder = New-Object System.Text.StringBuilder [void]$builder.AppendLine('-----BEGIN CERTIFICATE-----') [void]$builder.AppendLine([System.Convert]::ToBase64String($root.RawData, 'InsertLineBreaks')) [void]$builder.AppendLine('-----END CERTIFICATE-----') Set-Content -Path $certPath -Value $builder.ToString() -Encoding ASCII Write-Ok "Staged corp-root-ca.pem from root CA: $issuer" } catch { Write-Warn "Corp CA detection failed ($($_.Exception.Message)); continuing without it." } } # Confirm a dependency, offering a winget install when it is missing. Returns # $true when the dependency is present (or was just installed), $false when the # dev declined or install failed. function Confirm-Dependency { param( [Parameter(Mandatory)][string]$Command, [Parameter(Mandatory)][string]$DisplayName, [Parameter(Mandatory)][string]$WingetId, [string]$PostInstallNote ) if (Test-Command $Command) { Write-Ok "$DisplayName found." return $true } Write-Warn "$DisplayName not found (command '$Command')." if ($SkipDependencyInstall) { Write-Warn "Skipping install (-SkipDependencyInstall). Install '$WingetId' manually." return $false } if (-not (Test-Command 'winget')) { Write-Warn "winget is unavailable, so $DisplayName cannot be auto-installed." Write-Warn "Install it from the Microsoft Store / App Installer, then re-run." return $false } $answer = Read-Host " Install $DisplayName now via winget ($WingetId)? [y/N]" if ($answer -notmatch '^(y|yes)$') { Write-Warn "Skipped $DisplayName. It is required; re-run once it is installed." return $false } Write-Host " Running: winget install --id $WingetId" -ForegroundColor DarkGray winget install --id $WingetId --exact --accept-source-agreements --accept-package-agreements if ($LASTEXITCODE -ne 0) { Write-Warn "winget exited $LASTEXITCODE installing $DisplayName." return $false } if ($PostInstallNote) { Write-Warn $PostInstallNote } # winget updates the machine PATH, but this session will not see it until # relaunch, so re-probe rather than claim success outright. return (Test-Command $Command) } # Docker being installed is not the same as the engine running. A stopped # Docker Desktop passes the command check but fails every compose call. function Test-DockerEngine { try { docker info --format '{{.ServerVersion}}' 2>$null | Out-Null return ($LASTEXITCODE -eq 0) } catch { return $false } } # --- Resolve paths and channel ------------------------------------------------- $repoRoot = Split-Path -Parent $PSScriptRoot $config = $channels[$Channel] $branch = if ($Ref) { $Ref } else { $config.Ref } Write-Host "ShopDB dev bootstrap" -ForegroundColor White Write-Host " Channel : $Channel" -ForegroundColor White Write-Host " Branch : $branch" -ForegroundColor White Write-Host " Project : $($config.Project)" -ForegroundColor White Write-Host " Repo : $repoRoot" -ForegroundColor White # --- 1. Dependencies ----------------------------------------------------------- Write-Step 'Checking developer dependencies' $allPresent = $true $allPresent = (Confirm-Dependency -Command 'git' -DisplayName 'Git' -WingetId 'Git.Git') -and $allPresent $allPresent = (Confirm-Dependency -Command 'docker' -DisplayName 'Docker Desktop' -WingetId 'Docker.DockerDesktop' ` -PostInstallNote 'Docker Desktop needs a sign-out/restart and must be started once before use.') -and $allPresent if ($CheckPython) { $allPresent = (Confirm-Dependency -Command 'python' -DisplayName 'Python 3.11+' -WingetId 'Python.Python.3.11') -and $allPresent } if (-not $allPresent) { throw 'One or more required dependencies are missing. Resolve the warnings above and re-run.' } Write-Step 'Checking the Docker engine is running' if (-not (Test-DockerEngine)) { throw 'Docker is installed but the engine is not responding. Start Docker Desktop and re-run.' } Write-Ok 'Docker engine is responding.' # --- 2. Check out the channel branch ------------------------------------------ Write-Step "Preparing the '$branch' branch" Push-Location $repoRoot try { $dirty = git status --porcelain if ($dirty) { Write-Warn 'Working tree has uncommitted changes; leaving the current branch as-is.' Write-Warn "Building from the checked-out tree instead of switching to '$branch'." } else { git fetch origin $branch git checkout $branch git pull --ff-only origin $branch Write-Ok "On '$branch', up to date with origin." } # --- 3. Channel .env ------------------------------------------------------ Write-Step 'Ensuring a channel .env exists' $envPath = Join-Path $repoRoot ".env.$($config.Project)" if (Test-Path $envPath) { Write-Ok "Reusing existing $([System.IO.Path]::GetFileName($envPath))." # A .env written before the pull-based flow existed will not carry a # SHOPDB_IMAGE line, and the pull compose file requires it. Top it up in # place rather than force the pilot to delete and re-key the file. $image = "$imageRepo`:$($config.ImageTag)" $envText = Get-Content -Path $envPath if (-not ($envText | Where-Object { $_ -match '^SHOPDB_IMAGE=' })) { Add-Content -Path $envPath -Value "SHOPDB_IMAGE=$image" -Encoding ASCII Write-Ok "Added SHOPDB_IMAGE=$image to the existing .env." } } else { # Dev-grade secrets: generated locally, never for production. A real # deploy fills .env from the wiki runbook, not from this script. # # Get-Random is System.Random: a 32-bit seed, and all four values came # off one stream, so recovering the seed from any one of them recovers # the other three. These sign JWTs for a stack a pilot may point at a # real imported dataset, so they come from the CSPRNG instead. "Dev # grade" is about rotation and provenance, not about being guessable. $secret = [Convert]::ToBase64String( [System.Security.Cryptography.RandomNumberGenerator]::GetBytes(48)) $jwt = [Convert]::ToBase64String( [System.Security.Cryptography.RandomNumberGenerator]::GetBytes(48)) $dbPass = ([Convert]::ToBase64String( [System.Security.Cryptography.RandomNumberGenerator]::GetBytes(18))) -replace '[^A-Za-z0-9]', 'x' $rootPass = ([Convert]::ToBase64String( [System.Security.Cryptography.RandomNumberGenerator]::GetBytes(18))) -replace '[^A-Za-z0-9]', 'x' $apiPort = $config.ApiPort $mysqlPort = $config.MysqlPort $image = "$imageRepo`:$($config.ImageTag)" $lines = @( "# Auto-generated by scripts/dev-bootstrap.ps1 for the $Channel channel.", "# DEV-GRADE ONLY. Do not reuse these secrets for a production site.", "FLASK_APP=wsgi.py", "FLASK_ENV=production", "SECRET_KEY=$secret", "JWT_SECRET_KEY=$jwt", "DATABASE_URL=mysql+pymysql://shopdb:$dbPass@db:3306/shopdb_flask?charset=utf8mb4", "CORS_ORIGINS=https://localhost:$apiPort", "LOG_LEVEL=INFO", "MYSQL_ROOT_PASSWORD=$rootPass", "MYSQL_PASSWORD=$dbPass", "MYSQL_PORT=$mysqlPort", "API_PORT=$apiPort", "SHOPDB_IMAGE=$image", "SHOPDB_ENV_LABEL=$($config.EnvLabel)" ) Set-Content -Path $envPath -Value $lines -Encoding ASCII Write-Ok "Wrote $([System.IO.Path]::GetFileName($envPath)) (API on $apiPort, MySQL on $mysqlPort)." } # --- 4. Pull and start ---------------------------------------------------- # No local build: the image is produced by CI and published to GHCR (see # .github/workflows/publish-images.yml). Pilots may have only Docker # installed, and building the frontend from source behind an inspecting # proxy is unreliable, so we pull the finished channel image instead. Write-Step "Pulling and starting the '$($config.Project)' stack" $composeArgs = @( 'compose', '-p', $config.Project, '--env-file', $envPath, '-f', 'docker-compose.pull.yml' ) & docker @composeArgs pull if ($LASTEXITCODE -ne 0) { throw "docker compose pull failed ($LASTEXITCODE). If this is an auth error, run: docker login ghcr.io" } & docker @composeArgs up -d if ($LASTEXITCODE -ne 0) { throw "docker compose up failed ($LASTEXITCODE)." } Write-Step 'Done' Write-Ok "The $Channel stack is up." Write-Host " UI/API : https://localhost:$($config.ApiPort)" -ForegroundColor White if ($config.EnvLabel) { Write-Host " Badge : sidebar shows '$($config.EnvLabel)' (edge channel)." -ForegroundColor White } Write-Host " Logs : docker compose -p $($config.Project) logs -f api" -ForegroundColor White Write-Host " Stop : docker compose -p $($config.Project) down" -ForegroundColor White } finally { Pop-Location }