Initial commit: VMware vSphere API simulator scaffold.

Add the FastAPI app, PostgreSQL migrations, Docker/Helm packaging, API
contracts, docs, client examples, and the unit/integration/compatibility
test suite for local client and tooling labs without a real vCenter.

docker-compose.yml

@@ -0,0 +1,171 @@
+name: vmware-api-simulator
+
+x-simulator-env: &simulator-env
+  DATABASE_URL: postgresql://vmware:vmware@postgres:5432/vmware_simulator
+  ENABLE_PVE_STUB: "false"
+  SEED_VSPHERE_PROFILE: "${SEED_VSPHERE_PROFILE:-large}"
+  SEED_VSPHERE_LARGE_HOSTS: "${SEED_VSPHERE_LARGE_HOSTS:-10}"
+  SEED_VSPHERE_LARGE_VMS: "${SEED_VSPHERE_LARGE_VMS:-1000}"
+  LOG_LEVEL: INFO
+  TICKET_SIGNING_KEY: development-only-signing-key-change-me
+  APP_PORT: "8080"
+
+x-dev-env: &dev-env
+  DATABASE_URL: postgresql://vmware:vmware@postgres:5432/vmware_simulator
+  TEST_DATABASE_URL: postgresql://vmware:vmware@postgres:5432/vmware_simulator
+  ENABLE_PVE_STUB: "false"
+  SEED_VSPHERE_PROFILE: "${SEED_VSPHERE_PROFILE:-large}"
+  SEED_VSPHERE_LARGE_HOSTS: "${SEED_VSPHERE_LARGE_HOSTS:-10}"
+  SEED_VSPHERE_LARGE_VMS: "${SEED_VSPHERE_LARGE_VMS:-1000}"
+  LOG_LEVEL: INFO
+  TICKET_SIGNING_KEY: development-only-signing-key-change-me
+  APP_PORT: "8080"
+
+networks:
+  simulator:
+    driver: bridge
+
+volumes:
+  postgres-data:
+
+services:
+  postgres:
+    image: postgres:17.5-bookworm
+    restart: unless-stopped
+    networks: [simulator]
+    environment:
+      POSTGRES_DB: vmware_simulator
+      POSTGRES_USER: vmware
+      POSTGRES_PASSWORD: vmware
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U vmware -d vmware_simulator"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+      start_period: 5s
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+    ports:
+      - "127.0.0.1:5434:5432"
+
+  migrate:
+    build:
+      context: .
+      target: runtime
+    image: vmware-api-simulator:0.1.0
+    networks: [simulator]
+    env_file:
+      - path: .env
+        required: false
+    environment:
+      <<: *simulator-env
+    depends_on:
+      postgres:
+        condition: service_healthy
+    entrypoint: ["python"]
+    command: ["-m", "app.db.migrate_cli"]
+    restart: "no"
+
+  # FastAPI process — internal only. Clients use api-gateway :443.
+  simulator:
+    build:
+      context: .
+      target: dev
+    image: vmware-api-simulator-dev:0.1.0
+    restart: unless-stopped
+    networks: [simulator]
+    working_dir: /workspace
+    volumes:
+      - .:/workspace
+    env_file:
+      - path: .env
+        required: false
+    environment:
+      <<: *dev-env
+    depends_on:
+      migrate:
+        condition: service_completed_successfully
+    entrypoint: []
+    command:
+      [
+        "uvicorn",
+        "app.main:app",
+        "--host",
+        "0.0.0.0",
+        "--port",
+        "8080",
+        "--reload",
+        "--reload-dir",
+        "/workspace/app",
+        "--reload-include",
+        "*.html",
+      ]
+    healthcheck:
+      test:
+        [
+          "CMD",
+          "python",
+          "-c",
+          "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/ready', timeout=2)",
+        ]
+      interval: 10s
+      timeout: 3s
+      retries: 8
+      start_period: 20s
+    expose:
+      - "8080"
+
+  # Publishes vCenter HTTPS (and HTTP redirect face) → single simulator.
+  # See docs/ports.md
+  api-gateway:
+    image: nginx:1.28.0-alpine
+    restart: unless-stopped
+    networks: [simulator]
+    depends_on:
+      simulator:
+        condition: service_healthy
+    ports:
+      # Real vCenter defaults on the host (clients on other machines use these).
+      - "80:80"       # HTTP face
+      - "443:443"     # vCenter HTTPS (primary UI/API)
+    volumes:
+      - ./docker/gateway/vmware-ports.conf:/etc/nginx/conf.d/default.conf:ro
+      - ./docker/tls/server.crt:/etc/nginx/tls/server.crt:ro
+      - ./docker/tls/server.key:/etc/nginx/tls/server.key:ro
+    healthcheck:
+      test:
+        [
+          "CMD-SHELL",
+          "wget -qO- http://127.0.0.1/health/live || exit 1",
+        ]
+      interval: 10s
+      timeout: 3s
+      retries: 5
+      start_period: 5s
+    read_only: true
+    tmpfs:
+      - /var/cache/nginx
+      - /var/run
+      - /tmp
+    security_opt:
+      - no-new-privileges:true
+
+  dev:
+    profiles: [tools]
+    build:
+      context: .
+      target: dev
+    image: vmware-api-simulator-dev:0.1.0
+    networks: [simulator]
+    working_dir: /workspace
+    volumes:
+      - .:/workspace
+    env_file:
+      - path: .env
+        required: false
+    environment:
+      <<: *dev-env
+    depends_on:
+      postgres:
+        condition: service_healthy
+    entrypoint: []