Add a stateful Proxmox API console and broad handler coverage beyond the
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
This commit is contained in:
Sergey Antropoff
@@ -0,0 +1,168 @@
|
||||
# Getting started
|
||||
|
||||
Bring up a local laboratory cluster, authenticate, and exercise a first
|
||||
read/mutation cycle against the simulator.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Docker and Docker Compose
|
||||
- `make` (optional but used by the documented commands)
|
||||
|
||||
Python, linters, and tests run **inside** containers. You do not need a local
|
||||
Python toolchain for day-to-day use.
|
||||
|
||||
## Choose a path
|
||||
|
||||
| Path | When to use |
|
||||
|---|---|
|
||||
| [Published image](#1a-published-image-docker-hub) | Fastest lab using `inecs/proxmox-api-simulator` |
|
||||
| [Helm / Kubernetes](kubernetes.md) | Cluster install with Ingress + Let's Encrypt |
|
||||
| [Development checkout](#1b-development-checkout) | Contribute / bind-mount source / HTTPS gateway on `:8007` |
|
||||
|
||||
## 1a. Published image (Docker Hub)
|
||||
|
||||
Uses [`docker-compose.release.yml`](../docker-compose.release.yml) — PostgreSQL +
|
||||
runtime simulator from Hub. No source build required.
|
||||
|
||||
```bash
|
||||
# from this repository, or download docker-compose.release.yml alone
|
||||
docker compose -f docker-compose.release.yml pull
|
||||
docker compose -f docker-compose.release.yml up -d
|
||||
docker compose -f docker-compose.release.yml run --rm --entrypoint python \
|
||||
simulator -m app.simulation.seed_cli
|
||||
```
|
||||
|
||||
Pin a version:
|
||||
|
||||
```bash
|
||||
IMAGE_TAG=0.1.0 docker compose -f docker-compose.release.yml up -d
|
||||
```
|
||||
|
||||
Make helpers (git checkout):
|
||||
|
||||
```bash
|
||||
make release-up
|
||||
make release-seed PROFILE=small
|
||||
```
|
||||
|
||||
| Host port | Service |
|
||||
|---|---|
|
||||
| `8006` | HTTP API + Web UI |
|
||||
| `5432` | PostgreSQL (localhost only) |
|
||||
|
||||
Migrations run automatically via the `migrate` one-shot service.
|
||||
|
||||
Then continue from [Wait until ready](#2-wait-until-ready).
|
||||
|
||||
## 1b. Development checkout
|
||||
|
||||
```bash
|
||||
make install
|
||||
make up
|
||||
```
|
||||
|
||||
Services:
|
||||
|
||||
| Host port | Service |
|
||||
|---|---|
|
||||
| `8006` | HTTP API + Web UI |
|
||||
| `8007` | HTTPS nginx gateway → simulator |
|
||||
| `5432` | PostgreSQL (localhost only) |
|
||||
|
||||
Migrations apply automatically before the simulator becomes ready.
|
||||
|
||||
## 2. Wait until ready
|
||||
|
||||
```bash
|
||||
curl http://localhost:8006/health/live
|
||||
curl http://localhost:8006/health/ready
|
||||
```
|
||||
|
||||
`/health/ready` returns HTTP 503 until PostgreSQL is reachable **and** the
|
||||
latest packaged migration is applied.
|
||||
|
||||
## 3. Seed a profile
|
||||
|
||||
```bash
|
||||
make seed PROFILE=small
|
||||
```
|
||||
|
||||
`small` creates node `pve01`, two QEMU guests (`100`, `101`), one LXC (`200`),
|
||||
local storages, and the standard development principals. See
|
||||
[Seed profiles](seed-profiles.md) for other sizes.
|
||||
|
||||
## 4. Check the API version
|
||||
|
||||
```bash
|
||||
curl -s http://localhost:8006/api2/json/version | jq .
|
||||
```
|
||||
|
||||
The cold-start contract defaults to the bundled PVE **9.2.3** snapshot in Docker
|
||||
Compose. Switch majors 6–9 from the Web UI or
|
||||
[API versions](api-versions.md).
|
||||
|
||||
## 5. Authenticate
|
||||
|
||||
```bash
|
||||
curl -s -X POST \
|
||||
-d 'username=root@pam&password=secret' \
|
||||
http://localhost:8006/api2/json/access/ticket | jq .
|
||||
```
|
||||
|
||||
Save `ticket` and `CSRFPreventionToken` from `data`. For mutations, send:
|
||||
|
||||
- Cookie: `PVEAuthCookie=<ticket>`
|
||||
- Header: `CSRFPreventionToken: <token>`
|
||||
|
||||
Details: [Authentication](authentication.md).
|
||||
|
||||
## 6. List guests and start one
|
||||
|
||||
```bash
|
||||
# replace TICKET / CSRF from the previous response
|
||||
curl -s -H "Cookie: PVEAuthCookie=$TICKET" \
|
||||
http://localhost:8006/api2/json/nodes/pve01/qemu | jq .
|
||||
|
||||
curl -s -X POST \
|
||||
-H "Cookie: PVEAuthCookie=$TICKET" \
|
||||
-H "CSRFPreventionToken: $CSRF" \
|
||||
http://localhost:8006/api2/json/nodes/pve01/qemu/100/status/start | jq .
|
||||
```
|
||||
|
||||
Async operations return a UPID string. Poll until the task finishes:
|
||||
|
||||
```bash
|
||||
curl -s -H "Cookie: PVEAuthCookie=$TICKET" \
|
||||
"http://localhost:8006/api2/json/nodes/pve01/tasks/${UPID}/status" | jq .
|
||||
```
|
||||
|
||||
## 7. Open the Web UI
|
||||
|
||||
Visit [http://localhost:8006/](http://localhost:8006/) for the interactive
|
||||
console, contract catalog (PVE 6–9), compatibility view, runtime contract apply,
|
||||
and demo-cluster controls. See [Web UI](web-ui.md) for light/dark theme
|
||||
screenshots and the full feature list.
|
||||
|
||||
## 8. Try a client library
|
||||
|
||||
```bash
|
||||
# from the repository root after make up + seed
|
||||
python examples/python/proxmoxer_cookbook.py
|
||||
```
|
||||
|
||||
More stacks: [Clients](clients.md) and [`examples/`](../examples/README.md).
|
||||
|
||||
## You’re done when…
|
||||
|
||||
- `/health/ready` returns `{"status":"ok"}` (or equivalent OK body)
|
||||
- `/api2/json/version` reports the active contract version
|
||||
- Ticket login succeeds for `root@pam`
|
||||
- `nodes/pve01/qemu` lists seeded VMs
|
||||
- At least one power or create path returns a UPID that completes successfully
|
||||
|
||||
## Next steps
|
||||
|
||||
- [Configuration](configuration.md) — env vars, workers, contract path
|
||||
- [API versions](api-versions.md) — hot-swap majors 6–9
|
||||
- [Clients](clients.md) — Ansible, Terraform, Pulumi, Go, Java, Perl
|
||||
- [Operations](operations.md) — reseed, migrate, upgrades
|
||||
Reference in New Issue
Block a user