Local Developer Setup¶

Get from a clean laptop to "all tests green, docker stack up, gcloud authenticated" in about 45 minutes. Windows 11 corporate-managed machines are supported (there is a Group Policy workaround for the gcloud installer); macOS and Linux notes appear alongside each step.

You'll need:

A Google account added to GCP project mainframe-modernization-495412 (ask the team owner if you haven't been).
Read access to the repository.
A Windows 11 laptop or any Linux/macOS machine.

Using a different GCP project? Override two env vars before running the bootstrap — see If you're on a different project.

1. What you'll have when you're done¶

gcloud SDK installed and runnable.
ADC (Application Default Credentials) set up locally — no API keys or service-account JSON files.
.env at repo root with your project, region, model pins, and gcloud config dir.
Docker stack running the emulator + services.
Unit + integration tests green.
Live regression tests green against real Vertex.

2. Prerequisites¶

2.1 Docker Desktop¶

Install from docker.com. Sign in, wait for "Engine running".

docker --version
docker compose version

WSL2 backend is fine (Docker Desktop sets it up).

2.2 Python 3.12¶

Install Python 3.12 from python.org. Check "Add Python to PATH" or use the py launcher.

py -3.12 --version

If you get "Python was not found" (Microsoft Store stub), install via python.org and use py -3.12 instead of python.

2.3 Git¶

git-scm.com/download/win. Git Bash comes with it.

git --version

macOS / Linux¶

Docker Desktop or Docker Engine + Compose plugin.
Python 3.12 via your package manager (brew install python@3.12, apt install python3.12, etc.).
Git is usually pre-installed.

3. Clone the repo¶

cd <workspace-folder>
git clone <repo-url> Mainframe-Assist
cd Mainframe-Assist

4. Install Google Cloud SDK¶

4.1 Corporate-managed Windows (Group Policy blocks .exe/.bat/.cmd)¶

Use the standalone zip and the PowerShell wrapper inside it.

$ProgressPreference = "SilentlyContinue"
$url = "https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-windows-x86_64-bundled-python.zip"
$zip = Join-Path $env:Temp "gcloud-sdk.zip"

Invoke-WebRequest -Uri $url -OutFile $zip -UseBasicParsing
Expand-Archive -Path $zip -DestinationPath $env:USERPROFILE -Force
Remove-Item $zip

& "$env:USERPROFILE\google-cloud-sdk\bin\gcloud.ps1" version

You'll see something like Google Cloud SDK 5xx.x.x. If it says "blocked by group policy", use a non-corporate machine.

Don't run install.bat — it's blocked by policy. Use & "$env:USERPROFILE\google-cloud-sdk\bin\gcloud.ps1" … everywhere. The bootstrap script does this for you.

4.2 Non-corporate Windows¶

Standard installer from cloud.google.com/sdk/docs/install. Restart PowerShell after install.

4.3 Linux / macOS¶

curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-linux-x86_64.tar.gz
tar -xzf google-cloud-cli-linux-x86_64.tar.gz -C "$HOME"
"$HOME/google-cloud-sdk/install.sh" --quiet \
  --usage-reporting=false --command-completion=false \
  --path-update=true --install-python=false
exec "$SHELL" -l
gcloud --version

4.4 Linux via WSL¶

If you're on Windows but prefer WSL, the SDK also installs cleanly under ~/google-cloud-sdk/ in Ubuntu-24.04 (Node.js and pip come with the distro). Add ~/google-cloud-sdk/bin to ~/.bashrc.

5. GCP bootstrap¶

scripts/bootstrap-gcp.ps1 handles the whole GCP-side setup: auth, ADC, project, APIs, IAM role attempts, and writing .env.

5.1 What it does¶

gcloud auth login — browser sign-in with your Google account.
gcloud auth application-default login — sets up ADC.
Sets active project + ADC quota project.
Enables the 10 APIs the platform uses (Vertex AI, Firestore, Pub/Sub, Cloud Run, Secret Manager, Cloud Build, Artifact Registry, Cloud Logging, Cloud Monitoring, Discovery Engine).
Tries to bind dev IAM roles. If you only have roles/editor, some bindings warn "no projectIamAdmin" — that's fine; editor covers what dev needs.
Checks Firestore database status.
Smoke-tests ADC by fetching an access token.
Writes .env at the repo root with project, region, project number, model pins, and GCLOUD_CONFIG_DIR=%APPDATA%\gcloud (mounted into Docker containers for ADC).

5.2 Run it¶

.\scripts\bootstrap-gcp.ps1

Two browser pop-ups (auth + ADC). Finishes in ~3 minutes. Idempotent — safe to re-run.

Linux / macOS:

./scripts/bootstrap-local.sh

5.3 Verify `.env`¶

Get-Content .env

Expected shape (values will differ):

GOOGLE_CLOUD_PROJECT=mainframe-modernization-495412
GOOGLE_CLOUD_LOCATION=us-central1
GOOGLE_CLOUD_PROJECT_NUMBER=<project-number>
GOOGLE_GENAI_USE_VERTEXAI=true
GEMINI_PRO_MODEL=gemini-2.5-pro
GEMINI_FLASH_MODEL=gemini-2.5-flash
GCLOUD_CONFIG_DIR=<path-to-your-gcloud-config-dir>

.env is gitignored — never commit it.

6. Smoke-test Vertex Gemini¶

Prove the auth chain before going further.

py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"

# Load .env into the session (PowerShell doesn't auto-source .env files)
Get-Content .env | Where-Object { $_ -match '^[A-Z_][A-Z0-9_]*=' } | ForEach-Object {
    $k, $v = $_ -split '=', 2
    Set-Item -Path "Env:$k" -Value $v
}

.\.venv\Scripts\python.exe scripts\verify-vertex.py

Expected:

Project:  mainframe-modernization-495412
Location: us-central1
Model:    gemini-2.5-flash

Reply:    'pong'

OK — Vertex AI + ADC working end-to-end.

Linux / macOS:

python3.12 -m venv .venv
. .venv/bin/activate
pip install --upgrade pip
pip install -e ".[dev]"
set -a; . ./.env; set +a
python scripts/verify-vertex.py

If this fails, fix it before continuing. See §11 Troubleshooting.

7. Docker stack¶

Everything runs from Docker. All services are defined in docker-compose.yml.

7.1 First-time build¶

docker compose build
docker compose --profile test build tests

Takes ~5 minutes the first time.

7.2 Bring it up¶

docker compose up -d
docker compose ps

You should see the containers Up and the four emulators (healthy).

7.3 Useful URLs¶

Service	URL	For
Mailpit web UI	http://localhost:8025	Captured outbound emails
Mock z/OSMF	http://localhost:8080/health	Returns `{"status": "ok"}`
Pub/Sub emulator	localhost:8085	`PUBSUB_EMULATOR_HOST`
Firestore emulator	localhost:8086	`FIRESTORE_EMULATOR_HOST`
UI (dev)	http://localhost:3000	Next.js dashboard

8. Run tests¶

8.1 Unit + integration¶

docker compose run --rm tests pytest tests/unit tests/integration

Expected: xxx passed, 3 skipped. The 3 skips are intentional (baseline fixture with no abend).

8.2 Unit only (no Docker)¶

.\.venv\Scripts\python.exe -m pytest tests/unit

Runs in ~5 seconds against your local venv.

8.3 Where tests live¶

tests/unit/ — pure unit tests, mocked. Fast.
tests/integration/ — Docker emulators + mocked LLM. Tens of seconds.
tests/live/ — real Vertex Gemini. Gated on GOOGLE_CLOUD_PROJECT. Slow.
tests/manual/ — demo scripts, not pytest.

9. Live regression tests¶

Run when you change anything that touches Vertex (prompts, GeminiClient, evaluator logic).

# Region Selector (~2:20)
docker compose run --rm tests pytest tests/live/test_region_selector_live.py -v

# Hypothesis Investigator (~16:00 — slowest)
docker compose run --rm tests pytest tests/live/test_investigator_live.py -v

# Verifier critique (~12s)
docker compose run --rm tests pytest tests/live/test_verifier_live.py -v

Investigator is slow because it does 1 generator call + 5 evaluators × up to 2 tool calls per fixture, with 30 s pacing between fixtures to keep regional Vertex throughput happy.

10. Daily workflow¶

# Start of day
docker compose up -d

# When you change agent code or shared/
docker compose run --rm tests pytest tests/unit tests/integration

# When you change a prompt or LLM-touching code
docker compose run --rm tests pytest tests/live/test_<slice>_live.py -v

# End of day
docker compose down

Stop without losing state: docker compose stop keeps containers/data; docker compose down removes them.

Re-run bootstrap after gcloud auth expires:

.\scripts\bootstrap-gcp.ps1

Idempotent — re-auths and rewrites .env.

11. Troubleshooting¶

`verify-vertex.py` says `GOOGLE_CLOUD_PROJECT not set`¶

Your shell didn't load .env. Re-run the env-loading PowerShell snippet in §6, or restart your shell after bootstrap wrote .env.

`verify-vertex.py` says `404 NOT_FOUND` on the model¶

The model name in .env is wrong or retired.

.\.venv\Scripts\python.exe scripts\probe-vertex-models.py

Update .env with the working ones.

`gcloud.ps1 ... : This program is blocked by group policy`¶

You ran gcloud.cmd instead of gcloud.ps1. Any gcloud call on the corporate machine must use the .ps1 wrapper:

& "$env:USERPROFILE\google-cloud-sdk\bin\gcloud.ps1" <subcommand>

Live tests fail with `429 RESOURCE_EXHAUSTED`¶

Vertex regional shared pool is throttling. Wait 5 min, or switch region:

$env:GOOGLE_CLOUD_LOCATION = "us-east5"
.\.venv\Scripts\python.exe scripts\verify-vertex.py

If that works, edit .env to GOOGLE_CLOUD_LOCATION=us-east5.

Docker Desktop slow on Windows¶

Give it more memory/CPU in Settings → Resources.

`bootstrap-gcp.ps1` says `could not bind roles/aiplatform.user`¶

You don't have roles/projectIamAdmin. Fine — roles/editor implicitly covers everything dev needs. If verify-vertex.py works, IAM is fine.

`.venv` corrupted¶

Remove-Item -Recurse -Force .venv
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"

12. If you're on a different project¶

Override two env vars before running bootstrap:

$env:GCP_PROJECT_ID = "<your-project-id>"
$env:GCP_REGION     = "us-central1"     # or wherever
.\scripts\bootstrap-gcp.ps1

Linux / macOS:

GCP_PROJECT_ID=<your-project-id> GCP_REGION=us-central1 ./scripts/bootstrap-local.sh

The bootstrap reads those, falls back to Dexian-TIC defaults if absent, writes a fresh .env, and everything else picks up your values. No code changes required.