showroom-local-test

name	showroom:local-test
description	Prepare the local environment for testing the TARSy Showroom. Run this before opening localhost:8443 to verify module content changes. Checks that TARSy containers and the nginx proxy are running, builds the site with the local port, and ensures the httpd server is up.

Local test preparation skill

Prepare the local environment for testing the TARSy Showroom. Announce at the start: "I'm using showroom:local-test to prepare the local environment."

Context

The showroom repo is at the current working directory. The TARSy app repo is at ../clone/tarsy/ (relative to the showroom repo).

Local testing requires a two-step port override:

• Production ui-config.yml uses port: 8080 (oauth2-proxy, X-Frame-Options present)
• Local testing uses port: 8081 (nginx proxy, bypasses oauth2-proxy, strips X-Frame-Options)

The source file ui-config.yml must be reverted to port: 8080 after building. Only the built www/ui-config.yml and www/zero-config.yml should retain the local port.

Checklist

Work through each step in order. Report status as you go.

Step 1 — Check TARSy containers

Run: podman ps --format "{{.Names}}\t{{.Status}}"

Required containers and their expected states:

Container	Must be	Notes
tarsy-postgres	Up (healthy)	PostgreSQL
tarsy-llm	Up (healthy)	LLM gRPC service
tarsy-app	Up (healthy)	TARSy Go backend
tarsy-oauth2	Up (any)	oauth2-proxy — unhealthy is OK for local testing

If tarsy-postgres, tarsy-llm, or tarsy-app are missing or exited:

TARSy containers are not running.

Start them with:
  cd <path-to-tarsy-repo>
  podman compose -f deploy/podman-compose.yml up -d

Then run showroom:local-test again.

Stop here and wait for the user.

Step 2 — Check the nginx proxy

Look for a container named tarsy-local-proxy in the running container list.

If running: confirm it maps host port 8081 → container port 80. Proceed to Step 3.

If not running: start it:

podman run -d --rm --name tarsy-local-proxy \
  --network tarsy_default \
  -p 8081:80 \
  nginx:alpine \
  sh -c 'echo "server { listen 80; location / { proxy_pass http://tarsy-app:8080; proxy_hide_header X-Frame-Options; add_header Cache-Control no-store; } }" \
         > /etc/nginx/conf.d/default.conf && nginx -g \"daemon off;\""'

Wait 2 seconds, then verify it appears in podman ps. If it fails to start, report the error and stop.

Step 3 — Check seed data

Run inside the tarsy-app container:

podman exec tarsy-app wget -qO- http://localhost:8080/api/v1/sessions 2>/dev/null | python3 -c "
import sys, json
data = json.load(sys.stdin)
sessions = data.get('sessions', [])
print(len(sessions), 'sessions found')
"

If the result is 0 sessions found, offer to seed:

Demo data is not loaded. Run the seed script?

  podman exec tarsy-app python3 /home/rhel/tarsy/demo/seed.py

Or seed from the host if the script is available:
  python3 <path-to-tarsy-repo>/demo/seed.py

If 5 sessions are found, proceed silently. If fewer than 5 are found, note it but proceed.

Step 4 — Set local port and build

1. Read ui-config.yml and confirm the current port value.
2. Set port: 8081 in ui-config.yml.
3. Run the build: utilities/lab-build
4. Immediately revert ui-config.yml back to port: 8080 (do this before reporting results — do not wait).
5. Verify that www/ui-config.yml and www/zero-config.yml contain port: 8081 (the built copies should have the local port).

If lab-build fails, revert the port first, then report the error.

Step 5 — Ensure the httpd server is running

Check for a container named showroom-httpd in podman ps.

If running: note that it is already serving (volume-mounted, no restart needed).

If not running: start it:

utilities/lab-serve

Step 6 — Final report

Print a short status summary:

Local test environment ready.

  Showroom: http://localhost:8443/index.html
  TARSy (direct): http://localhost:8081
  TARSy (oauth2): http://localhost:8080

What to check:
  Module 01 — Notable sessions section (HighErrorRate, NodePressure, DeploymentFailing)
  Module 02 — Score tab section and expanded Trace tab
  Module 03 — 5-item closing recap

Note: ui-config.yml is reverted to port 8080. The built www/ files use port 8081.
Do not commit ui-config.yml while port is 8080 — it is already correct for production.