Manual Blue/Green Deploys to qa.tokenoftrust.com

What is this and when to use it?

qa.tokenoftrust.com is our temporary QA environment spun up for the Node 16 → 20 port. It mirrors test.tokenoftrust.com sign-in and runs all services under the tot-qa user at:

/home/tot-qa/services/tot-qa

Until CI/CD fully supports QA, developers can manually deploy any branch here using our blue/green layout:

• blue/ and green/ are git work trees built independently.
• app is a symlink pointing to whichever color is live.
• We intentionally use the legacy PM2 config: tot-qa.json (managed by Ansible).

Goal: Fast, safe, reversible branch validation in QA during the migration window.
Guardrails: Always restart PM2 with tot-qa.json.

TL;DR — Copy/Paste Flow

# 0) SSH & cd
# ssh tot-qa@qa.tokenoftrust.com
# cd ~/services/tot-qa

# 1) Choose target color for your branch (prefers color already on your branch)
BRANCH=my-feature-branch
COLOR=$(./switchBlueGreen.sh -n -b "$BRANCH") && echo "Target color: $COLOR"

# 2) Build the inactive color from your branch (LEGACY path)
# ⚠️ CRITICAL: Check if build succeeds before continuing to step 3
if ./updateInstallBuild.sh -c "$COLOR" -b "$BRANCH"; then
    echo "✅ Build succeeded, proceeding to deployment"
else
    echo "❌ Build failed - ABORTING DEPLOYMENT"
    echo "DO NOT run setColor.sh - traffic will stay on working build"
    exit 1
fi

# 3) Flip to that color (LEGACY restart with tot-qa.json)
# ⚠️ ONLY run this if step 2 succeeded
./setColor.sh -c "$COLOR"
pm2 startOrGracefulReload tot-qa.json --wait-ready --listen-timeout 120000
sleep 5 && pm2 reset tot-qa

# 4) Validate: aboutApp.json SHA must match the running app
EXPECTED=$(git -C app rev-parse --short HEAD)
./test-restart-validation.sh https://qa.tokenoftrust.com/aboutApp.json "$EXPECTED"

Background you’ll care about

Why blue/green?

Blue/green lets us prepare a full build (code + deps + webpack bundles) offline in one color, then flip traffic by switching the app symlink and reloading PM2. It’s instant to roll back by flipping back.

Directory layout (QA host)

~/services/tot-qa/
  ├─ blue/            # one full build
  ├─ green/           # the other full build
  ├─ app -> blue|green  # ACTIVE color symlink
  ├─ tot-qa.json      # legacy PM2 ecosystem file (use this)
  ├─ .env             # env for HOST/PORT/keys (create once, then edit)
  └─ bin/*.sh, *.sh   # helper scripts listed below

Helper scripts you’ll use

• updateInstallBuild.sh — Resets/fetches, checks out the branch, selects the right lockfile for Node 16/20, installs, builds.
• switchBlueGreen.sh — Suggests or switches blue/green based on current/live/branch.
• setColor.sh — Updates the app symlink; in legacy mode it leaves PM2 config at tot-qa.json.
• test-restart-validation.sh — Wait/retry loop to confirm aboutApp.json SHA matches.

Rollback (instant)

OTHER=$(./switchBlueGreen.sh -n)   # opposite of current symlink
./setColor.sh -c "$OTHER"
pm2 startOrGracefulReload tot-qa.json --wait-ready --listen-timeout 120000
sleep 5 && pm2 reset tot-qa

Frequently Asked Questions

Who can deploy to QA?

Anyone with SSH to the tot-qa account on qa.tokenoftrust.com.

npm ci failed—what now?

updateInstallBuild.sh already tries the correct lockfile and falls back to npm install when safe. Just re-run:

./updateInstallBuild.sh -c "$COLOR" -b "$BRANCH"

Check npm-ci.log / npm-install.log if it persists.

SHA mismatch after deploy?

1. Re-run the validator; 2) ensure app points to your color; 3) confirm bundles contain the SHA.

readlink app
./verify-deployed-sha.sh https://qa.tokenoftrust.com/aboutApp.json website/dist

Logs & status?

pm2 status
pm2 logs tot-qa --lines 200

Appendix — One-liners you’ll reuse

Blue/green target suggestion

BRANCH=my-feature-branch
./switchBlueGreen.sh -n -b "$BRANCH"

Build inactive color

./updateInstallBuild.sh -c "$COLOR" -b "$BRANCH"

Flip + restart (legacy)

./setColor.sh -c "$COLOR"
pm2 startOrGracefulReload tot-qa.json --wait-ready --listen-timeout 120000
sleep 5 && pm2 reset tot-qa

Validate SHA

EXPECTED=$(git -C app rev-parse --short HEAD)
./test-restart-validation.sh https://qa.tokenoftrust.com/aboutApp.json "$EXPECTED"