| 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
- Read
ui-config.yml and confirm the current port value.
- Set
port: 8081 in ui-config.yml.
- Run the build:
utilities/lab-build
- Immediately revert
ui-config.yml back to port: 8080 (do this before reporting results — do not wait).
- 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.
