Skip to content

Scripts reference

All PowerShell scripts live in scripts/ at the repo root, alongside the pre-existing bash scripts they complement (not replace - see "Relationship to existing scripts" below). Run them from the repository root (.\scripts\<name>.ps1), Windows PowerShell 5.1 or later. Every script: validates its prerequisites before doing anything, prints colored progress (==> steps, OK/ WARNING/FAIL results), never embeds a secret value, and returns exit code 0 on success / non-zero on the first failure.

build.ps1

  • Purpose: build the backend and frontend Docker images with a resolvable tag, optionally import into k3d or push to a registry.
  • Prerequisites: Docker Desktop running. -Local also needs k3d on PATH and the target cluster to already exist.
  • Files involved: backend/Dockerfile, frontend/Dockerfile.
  • Command: .\scripts\build.ps1 -Local (local k3d) or .\scripts\build.ps1 -Tag <sha> -Push -Registry <repo> (push).
  • Expected result: two tagged images (akshayabazaar-backend:<tag>, akshayabazaar-frontend:<tag>; plus :local aliases and a k3d import when -Local is set).
  • How to verify: docker images | Select-String akshayabazaar.
  • Common failure scenarios: Docker daemon not running (docker info check fails fast); -Push without -Registry; k3d cluster name mismatch (-Local without -K3dCluster pointed at the right cluster).
  • Rollback: none needed - building an image has no effect on anything running until you deploy it.

deploy-local.ps1

  • Purpose: helm upgrade --install against the local k3d cluster using values-local-staging.yaml.
  • Prerequisites: cluster reachable, images built/imported (build.ps1 -Local), the akshayabazaar-local-secrets Secret already applied in the target namespace.
  • Files involved: helm/akshayabazaar/, helm/akshayabazaar/values-local-staging.yaml.
  • Command: .\scripts\deploy-local.ps1
  • Expected result: migration Job succeeds as a pre-upgrade hook; backend/frontend 1/1 Running.
  • How to verify: .\scripts\verify-staging.ps1 -Context k3d-akshaya-staging -Namespace staging -ReleaseName akshaya-local -IngressHost staging.akshaya.local -IngressPort 8080
  • Common failure scenarios: see environments/local/README.md "Common failure scenarios" (the NetworkPolicy/migration-hook deadlock and the backend-Service label requirement, both diagnosed live against this exact cluster earlier in this branch's history). On any helm upgrade failure this script automatically prints the migration Job's pod logs for you.
  • Rollback: helm rollback akshaya-local <REVISION> -n staging, or re-run rollback-staging.ps1 -Context k3d-akshaya-staging -Namespace staging -ReleaseName akshaya-local -Yes.

deploy-staging.ps1

  • Purpose: PowerShell equivalent of scripts/deploy-staging.sh (which is what Jenkins actually runs) for a human deploying to the real staging cluster from Windows.
  • Prerequisites: $env:KUBECONFIG pointed at a real staging kubeconfig; akshayabazaar-staging-secrets Secret already applied.
  • Files involved: helm/akshayabazaar/, helm/akshayabazaar/values-staging.yaml.
  • Command: 
    $env:KUBECONFIG = "C:\path\to\kubeconfig-staging.yaml"
.\scripts\deploy-staging.ps1 -ImageTag <commit-sha>
  • Expected result: helm upgrade --install --atomic --wait completes; migration Job succeeds.
  • How to verify: .\scripts\verify-staging.ps1
  • Common failure scenarios: missing/empty -ImageTag (rejected outright - never accepts latest); missing Secret (checked and rejected before helm upgrade even runs); a failed upgrade auto-rolls-back via --atomic (Helm's own behavior, not scripted here) and this script then prints the migration Job's previous logs for diagnosis.
  • Rollback: not normally needed (--atomic already handles a failed upgrade). For a deploy that succeeded but is behaviorally wrong: .\scripts\rollback-staging.ps1 -Yes.
  • Not yet executed against real infrastructure: this environment only had reachable access to the local k3d cluster - see docs/devops/README.md "Items requiring your approval".

verify-staging.ps1

The primary post-deploy validation command. Fully documented in verification.md - summary here:

  • Purpose: read-only, end-to-end check of a deployment (Docker → cluster → namespace → pods → deployments → services → ingress → frontend → backend/API health → DB → Redis), each with a PASS/WARN/FAIL result.
  • Command: .\scripts\verify-staging.ps1 (real staging defaults) or with -Context/ -Namespace/-ReleaseName/-IngressHost/-IngressPort overrides for local/dev.
  • Rollback: not applicable - this script makes no changes.

restart-staging.ps1

  • Purpose: kubectl rollout restart on backend+frontend without a new image or Helm values change - e.g. after an out-of-band ConfigMap/Secret edit, or to clear a stuck pod.
  • Files involved: none (cluster-only operation).
  • Command: .\scripts\restart-staging.ps1
  • Expected result: both Deployments roll pod-by-pod (no downtime - the chart's maxUnavailable: 0 strategy requires the new pod Ready before the old one terminates).
  • How to verify: .\scripts\verify-staging.ps1
  • Common failure scenarios: rollout exceeds -TimeoutSeconds (default 180) - usually means the new pod isn't passing its readiness probe; kubectl describe deployment/<name> for the reason.
  • Rollback: re-run the script again (idempotent), or kubectl rollout undo deployment/<name>.

stop-staging.ps1

  • Purpose: scale backend+frontend to 0 replicas - pause, not delete. Does not uninstall the Helm release or touch MySQL/Redis/PVC/Secret/NetworkPolicy/Ingress.
  • Command: .\scripts\stop-staging.ps1 (dry run - prints what would happen) then .\scripts\stop-staging.ps1 -Yes (actually scales down).
  • Expected result: kubectl get pods -n <namespace> shows no backend/frontend pods; MySQL/ Redis pods (if namespace-local, as in the local k3d topology) are unaffected.
  • Common failure scenarios: Deployment not found (already stopped, or wrong -ReleaseName) - reported as a per-Deployment error, not a hard failure of the whole script.
  • Rollback: re-run the matching deploy script (deploy-local.ps1/deploy-staging.ps1), which reasserts replicaCount from the Helm values.

rollback-staging.ps1

  • Purpose: helm rollback to a previous revision.
  • Command: .\scripts\rollback-staging.ps1 (dry run - prints helm history only) then .\scripts\rollback-staging.ps1 -Yes (rolls back one revision) or .\scripts\rollback-staging.ps1 -Revision <N> -Yes (rolls back to a specific revision).
  • Expected result: release reverts to the target revision's chart+values+image tags.
  • How to verify: .\scripts\verify-staging.ps1
  • Common failure scenarios: release not found in the given namespace (check -Namespace/ -ReleaseName); revision doesn't exist (helm history printed first, always, so you can check before committing).
  • Rollback of a rollback: helm rollback <release> <REVISION> again, targeting whichever revision you want - Helm keeps full history (default 10 revisions).

Relationship to existing scripts

This pass adds PowerShell scripts; it does not replace the pre-existing bash scripts, which serve a different runner:

Existing (bash) New (PowerShell) Relationship
scripts/deploy-staging.sh scripts/deploy-staging.ps1 Same Helm command, different shell - .sh is what Jenkins (Linux) runs; .ps1 is for a human on Windows running the same deploy manually.
scripts/deploy-production.sh (none yet) No PowerShell production script by design - see environments/prod/README.md; production deploys go through Jenkins's manual-approval gate, not ad-hoc local scripts.
scripts/smoke-test.sh scripts/verify-staging.ps1 Complementary, not duplicate. smoke-test.sh is black-box HTTP-only (what Jenkins runs immediately post-deploy, environment-agnostic). verify-staging.ps1 is Kubernetes-aware (pods/deployments/services/endpoints/NetworkPolicy-mediated in-cluster checks) - it can tell you why an HTTP check would fail, not just that it did.
scripts/mysql-backup.sh, scripts/apply-r2-lifecycle.sh (none) Out of scope for this pass - unrelated to deploy/verify workflow.