03.02.WUI Setup

03.02. WUI Setup

Prerequisites

Node.js 18+ and npm
Docker and Docker Compose
GCP service account keys (for deployment)
Git access to all bnc-cpt-* repositories

Local Development Setup

1. Clone Repositories

mkdir -p /opt/bnc/bnc-cpt && cd /opt/bnc/bnc-cpt
for repo in bnc-cpt-api bnc-cpt-wui bnc-cpt-utl bnc-cpt-inf bnc-cpt-cnf tpl-gen; do
  git clone git@github.com:csitea/$repo.git
done

2. Install Dependencies

cd /opt/bnc/bnc-cpt/bnc-cpt-wui/src/vue/app
npm install

3. Environment Variables

Create .env file:

cat > .env << 'EOF'
VITE_API_BASE_URL=/api
EOF

The Vite dev server proxies /api requests to localhost:8100 (the API backend).

4. Run Dev Server

npm run dev
# WUI runs on http://localhost:3333

The API backend must be running on port 8100 for the proxy to work. Start it via:

# Option A: Direct Python
cd /opt/bnc/bnc-cpt/bnc-cpt-api/src/python/cpt-api
source .venv/bin/activate && python run.py

# Option B: Docker
cd /opt/bnc/bnc-cpt/bnc-cpt-utl && make do-setup-api

5. Docker-Based Setup (Alternative)

cd /opt/bnc/bnc-cpt/bnc-cpt-utl
export UID=$(id -u) GID=$(id -g)
make do-setup-wui

Build for Production

cd /opt/bnc/bnc-cpt/bnc-cpt-wui/src/vue/app

# Standard build
npm run build

# Environment-specific build (sets API base URL)
npm run build:dev
npm run build:tst
npm run build:prd

Output goes to dist/ directory.

GCP Service Account Keys

For deployment, place service account keys at:

~/.gcp/.bnc/
├── key-bnc-cpt-inf.json
├── key-bnc-cpt-dev.json
├── key-bnc-cpt-tst.json
├── key-bnc-cpt-prd.json
└── key-bnc-cpt-all.json

CI/CD Setup

GitHub Repository Variables

Set in Settings > Secrets and variables > Actions > Variables:

Variable	Value
ORG	`bnc`
APP	`cpt`
PROJ	`bnc-cpt-wui`
GH_ORG	`csitea`

GitHub Repository Secrets

Set in Settings > Secrets and variables > Actions > Secrets:

Secret	Description
ALL_CSI_GITHUB_TOKEN	Personal access token for cloning team repos
GCP_SA_KEY_INF	Content of `key-bnc-cpt-inf.json`
GCP_SA_KEY_DEV	Content of `key-bnc-cpt-dev.json`
GCP_SA_KEY_TST	Content of `key-bnc-cpt-tst.json`
GCP_SA_KEY_PRD	Content of `key-bnc-cpt-prd.json`

These are provisioned automatically by Terraform step 120-github-general-secrets.

CI/CD Workflow (`ci.yaml`)

Single workflow with 4 jobs:

build-and-test: Runs on all pushes. Builds Docker container, runs do_build_wui_vue (npm install + type-check + build). Runs UI tests against local dev server.
prepare-deploy: Determines target environments (inf+dev on master push, selected env on dispatch).
deploy: Builds Vue app with version, syncs to GCS bucket, invalidates CDN, health checks.
post-deploy-test: Runs the-bot Puppeteer suite against the deployed environment URL. Fetches test credentials (Stripe test card, PayPal test user) from GCP Secret Manager. Skips production. Uploads Mochawesome HTML report as artifact.
Auto-deploy: inf + dev on master push
Manual deploy: tst, prd via workflow_dispatch only
Protected: tst/prd blocked unless triggered manually
Post-deploy tests: Run against inf, dev, tst (never prd)

GitHub Team Requirement

The CI cloning step discovers repos via GitHub API team endpoint. Ensure:

Team team-bnc-cpt-int exists in the GitHub org
All bnc-cpt-* repos are members
ALL_CSI_GITHUB_TOKEN has read:org and repo scopes

GCP Infrastructure Prerequisites

Before WUI deployment, these Terraform steps must be provisioned:

cd /opt/bnc/bnc-cpt/bnc-cpt-utl

# 1. Enable GCP APIs
make do-generate-config-for-step ENV=dev STEP=001-enable-gcp-services
make do-provision ENV=dev STEP=001-enable-gcp-services

# 2. DNS zones and records
make do-generate-config-for-step ENV=dev STEP=007-dns
make do-provision ENV=dev STEP=007-dns

# 3. GCS bucket + HTTPS LB + CDN + SSL certificate
make do-generate-config-for-step ENV=dev STEP=015-gcp-buckets-for-sites-static
make do-provision ENV=dev STEP=015-gcp-buckets-for-sites-static

# 4. GitHub Actions secrets (for CI/CD)
make do-generate-config-for-step ENV=dev STEP=120-github-general-secrets
make do-provision ENV=dev STEP=120-github-general-secrets

Version Tagging

Version tags are the source of truth for deployed versions:

cd /opt/bnc/bnc-cpt/bnc-cpt-utl

# Bump version (default: patch, target: bnc-cpt-wui)
./run -a do_version_bump

# Push the tag
git -C /opt/bnc/bnc-cpt/bnc-cpt-wui push origin <tag>

The CI/CD workflow reads the latest git tag and injects it as <meta name="version"> in the built HTML.

Verification

After setup:

# Local dev server
curl http://localhost:3333

# Deployed
curl -s https://dev.carpulsetracker.com/index.html | grep 'meta name="version"'