Merge the wilm work, act on the five-agent review, verify the launch-path policy on Windows
This commit is contained in:
354
scripts/dev-bootstrap.ps1
Normal file
354
scripts/dev-bootstrap.ps1
Normal file
@@ -0,0 +1,354 @@
|
||||
<#
|
||||
.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
|
||||
}
|
||||
Reference in New Issue
Block a user