Rabbit Hole Demo

Use this skill inside the Rabbit Hole repository when the goal is to get the app demo-ready fast, recover the local stack, or verify that the backend is using Aerospike and live Airbyte.

Scope

This skill is for the local Rabbit Hole project only. It is most useful when:

• Docker services need to be started or recovered
• the backend must be restarted onto Aerospike after infrastructure comes up
• the frontend dev server needs to be brought back after stale Next.js assets or missing CSS
• the demo stack needs a quick health check before showing it live

Startup workflow

1. Start Docker Desktop first if the Docker socket is unavailable.
2. Start or verify the project containers:
   • airbyte-abctl-control-plane
   • rabbit-hole-minio
   • aerospike
   • infra-postgres-1
3. Start the backend from backend/:
   • ./venv/bin/python -m uvicorn main:app --host 127.0.0.1 --port 8000
4. Start the frontend from frontend/:
   • npm run dev -- --port 3001

Health checks

Run these checks after startup:

• Docker socket:
  • curl --unix-socket ~/.docker/run/docker.sock http://d/_ping
  • Expect OK
• Backend metadata:
  • curl http://127.0.0.1:8000/api/meta
  • Expect store to be aerospike
  • Expect Airbyte label to be Airbyte Actual
• Frontend:
  • open http://localhost:3001
• Airbyte:
  • curl http://127.0.0.1:8006/api/public/v1/health
• MinIO UI:
  • open http://localhost:9001

Common fixes

Docker Desktop is open but Docker hangs

• Restart Docker Desktop until the Docker socket responds.
• If the socket exists but requests hang, fully stop Docker Desktop and relaunch it cleanly.
• Do not prune or delete images, containers, or VM data unless explicitly asked.

Backend falls back to local-persistent store

• This usually means the backend started before Aerospike was healthy.
• Restart the backend after aerospike is up.
• Confirm with /api/meta before calling the demo ready.

Airbyte container is up but the UI or API is not healthy yet

• Check the Kubernetes workloads inside the control-plane container:
  • docker exec airbyte-abctl-control-plane kubectl get deployments -n airbyte-abctl
  • docker exec airbyte-abctl-control-plane kubectl get pods -n airbyte-abctl
• Wait until the main deployments are 1/1 before relying on Airbyte in a demo.

Frontend CSS disappears or the page loads unstyled

• Stop the Next.js dev server.
• Remove or move frontend/.next.
• Restart npm run dev -- --port 3001.
• Hard refresh the browser after restart.

Demo notes

• Prefer quick mode for faster live runs.
• The research view includes:
  • graph filtering by entity type
  • a results list alongside the graph
  • follow-up question entry after a run completes
• If the backend is already healthy and the demo is short, verify /api/meta and a homepage load instead of running a full research cycle.

Safety

• Avoid destructive git commands.
• Avoid deleting Docker data.
• Prefer targeted restarts and health checks over broad resets.