Sergey Antropoff
777926487b
initial QEMU slice, backed by imported contracts for majors 6–9. - Implement durable handlers for access/auth, cluster, LXC, storage, HA, firewall, Ceph, SDN, ACME, notifications, pools, mapping, and node ops - Serve an interactive Web UI with catalog browsing, demo seed controls, and OpenAPI/help surfaces - Bundle PVE 6.4-15, 7.4-16, and 8.4.5 contract revisions alongside 9.2.3 - Support in-memory runtime contract Apply (POST /ui/api/contract/apply) so /version and /api2 routes follow the selected major until restart - Expand seed profiles (including demo-cluster), migrations 007–008, TLS gateway config, Compose/Makefile tooling, and compatibility evidence - Tighten .gitignore for macOS, hidden directories (.*/), and local secrets
3.4 KiB
Configuration
Application settings are loaded from the environment (see .env.example).
Docker Compose injects many of these for the simulator service; values
declared under environment: in docker-compose.yml override .env for that
service.
Core
| Variable | Default / example | Meaning |
|---|---|---|
APP_HOST |
0.0.0.0 |
Bind address |
APP_PORT |
8006 |
HTTP listen port |
DATABASE_URL |
postgresql://proxmox:proxmox@postgres:5432/proxmox_simulator |
asyncpg DSN |
DB_POOL_MIN_SIZE |
1 |
Pool minimum |
DB_POOL_MAX_SIZE |
10 |
Pool maximum |
DB_CONNECT_TIMEOUT_SECONDS |
10 |
Connect timeout |
DB_COMMAND_TIMEOUT_SECONDS |
30 |
Command timeout |
LOG_LEVEL |
INFO |
Logging level |
REQUEST_ID_HEADER |
X-Request-ID |
Request correlation header |
Contract and catalog
| Variable | Meaning |
|---|---|
CONTRACT_SNAPSHOT |
Path to the normalized snapshot loaded at cold start |
CONTRACT_FALLBACK |
error (default), schema-default, or fixture — behaviour for methods without a semantic handler |
COMPATIBILITY_EVIDENCE |
Optional evidence JSON used by compatibility reports |
CATALOG_ARTIFACT_URL_6 … _9 |
Official API Viewer URLs used when importing/caching catalog majors |
Runtime hot-swap (Web UI / POST /ui/api/contract/apply) replaces the in-memory
route table for majors 6–9 without rewriting CONTRACT_SNAPSHOT. A process
restart restores the cold-start snapshot. See API versions.
With 100% handler coverage on majors 6–9, CONTRACT_FALLBACK is unused for
declared methods of the active contract. Keep error in production-like labs so
any accidental gap surfaces as HTTP 501.
Security and tasks
| Variable | Meaning |
|---|---|
TICKET_SIGNING_KEY |
HMAC key for tickets and ticket-bound CSRF tokens (change outside toy labs) |
TASK_WORKER_CONCURRENCY |
Number of leased asyncio workers (1–32) |
TASK_LEASE_SECONDS |
PostgreSQL task lease duration |
SIMULATION_TIME_SCALE |
Accelerates simulated task durations |
Seed and client test hooks
| Variable | Meaning |
|---|---|
SEED_PROFILE |
Profile name for the seed CLI (small, medium, …) |
SEED_LARGE_NODES |
Node count for large |
SEED_LARGE_RESOURCES |
Guest count for large (default 10 000) |
TEST_DATABASE_URL |
Integration-test DSN |
PROXMOXER_HOST / PROXMOXER_PORT |
Compatibility test client target (tls-gateway / 8443 in Compose) |
Ports and TLS
| Endpoint | Use |
|---|---|
http://localhost:8006 |
Direct HTTP (curl, browsers, most examples) |
https://localhost:8007 |
TLS gateway for TLS-assuming clients (proxmoxer, etc.) |
The checked-in certificate under docker/tls/ is disposable development
material. Never reuse it outside local labs. See Security.
Compose notes
migrateruns once;simulatorwaits for a successful migrate.- Development Compose bind-mounts the repository and enables Uvicorn reload.
- The default Compose
CONTRACT_SNAPSHOTpins the bundled PVE 9.2.3 revision for cold start.
Open and unused example keys
.env.example may still list keys such as PVE_API_VERSION,
SIMULATION_SEED, SIMULATOR_ADMIN_ENABLED, and SIMULATOR_ADMIN_TOKEN that
are not consumed by the current settings model. Prefer CONTRACT_SNAPSHOT
for the default major and the Web UI / apply API for runtime switches. Do not
assume an authenticated /_simulator admin API exists today.