Initial release of the oVirt/RHV Engine API simulator.

Stateful FastAPI lab with contract packs, Compose/Helm, Docker Hub release
targets, and Pulumi coverage across all Engine series (GET/POST/PUT/DELETE/HEAD).

docs/troubleshooting.md

@@ -0,0 +1,58 @@
+**Language / Язык:** [English](troubleshooting.md) | [Русский](ru/troubleshooting.md)
+
+# Troubleshooting
+
+## `/health/ready` returns 503
+
+- Wait for `migrate` to finish: `docker compose ps`
+- Check Postgres: `docker compose logs postgres`
+- Recreate: `make restart`
+
+## TLS / certificate errors
+
+Compose uses a self-signed cert on the Engine port. Use `curl -k` or client
+`insecure` / `verify=False` flags in labs. See [Security](security.md).
+
+## Port already in use
+
+Change host publish ports:
+
+```bash
+OVIRT_ENGINE_PORT=7443 OVIRT_UI_PORT=7080 make up
+```
+
+## Empty inventory / missing users
+
+Run seed:
+
+```bash
+make seed
+# or
+make seed-demo
+```
+
+## Wrong API major / missing fields
+
+Set `Version: 4` (or `3`) or use `/ovirt-engine/api/v4/...`. Confirm
+`OVIRT_SERIES` matches the pack you expect ([api-versions.md](api-versions.md)).
+
+## Client suite failures
+
+Ensure the stack is up and seeded, then run smoke first:
+
+```bash
+make up && make seed && make smoke
+make test-smoke-all
+```
+
+Disable HTTP proxies for local multi-hop clients (`unset HTTP_PROXY HTTPS_PROXY …`).
+
+## Still stuck
+
+Collect:
+
+```bash
+docker compose ps
+docker compose logs --tail=200 simulator api-gateway migrate
+curl -sk -i https://127.0.0.1/health/ready
+```