{"id":50822468,"url":"https://github.com/client-api/proxmox-docker","last_synced_at":"2026-06-13T15:04:09.505Z","repository":{"id":359960633,"uuid":"1248109376","full_name":"client-api/proxmox-docker","owner":"client-api","description":"Test-only Docker images for the four Proxmox products. These images are for E2E testing only. Do not run them in production.","archived":false,"fork":false,"pushed_at":"2026-05-24T11:22:52.000Z","size":58,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-24T11:26:20.504Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/client-api.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-24T07:39:47.000Z","updated_at":"2026-05-24T11:22:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/client-api/proxmox-docker","commit_stats":null,"previous_names":["client-api/proxmox-docker"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/client-api/proxmox-docker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/client-api%2Fproxmox-docker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/client-api%2Fproxmox-docker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/client-api%2Fproxmox-docker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/client-api%2Fproxmox-docker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/client-api","download_url":"https://codeload.github.com/client-api/proxmox-docker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/client-api%2Fproxmox-docker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34288668,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-13T02:00:06.617Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-13T15:04:08.608Z","updated_at":"2026-06-13T15:04:09.492Z","avatar_url":"https://github.com/client-api.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# proxmox-docker\n\nTest-only Docker images for the four Proxmox products — built so SDK\nclients generated from the Proxmox OpenAPI specs can be E2E-tested\nagainst a real Proxmox API surface inside GitHub Actions.\n\n\u003e [!WARNING]\n\u003e **These images are for E2E testing only. Do not run them in production.**\n\u003e\n\u003e They ship with **public, hard-coded credentials** (`root@pam` / `proxmox123`),\n\u003e a **self-signed TLS cert**, **no firewall**, and the daemons run inside a\n\u003e `--privileged` container. Workload paths (VM, LXC, real backups, mail\n\u003e filtering, clustering across nodes) are deliberately broken or absent.\n\u003e\n\u003e The goal is to give SDK test suites a real Proxmox HTTP API to talk to.\n\u003e If you need a real Proxmox install, use the upstream ISO at\n\u003e \u003chttps://www.proxmox.com/en/downloads\u003e.\n\n| Product | Image | API port | Default base path |\n|---------|--------------------------------------------------|----------|-------------------|\n| Proxmox VE                  | `ghcr.io/client-api/proxmox-docker/pve-test` | 8006 | `/api2/json` |\n| Proxmox Backup Server       | `ghcr.io/client-api/proxmox-docker/pbs-test` | 8007 | `/api2/json` |\n| Proxmox Mail Gateway        | `ghcr.io/client-api/proxmox-docker/pmg-test` | 8006 | `/api2/json` |\n| Proxmox Datacenter Manager  | `ghcr.io/client-api/proxmox-docker/pdm-test` | 8443 | `/api2/extjs` |\n\n## Status\n\nThese images run **real** Proxmox daemons (`pveproxy`, `pmxcfs`, `proxmox-backup-proxy`, …),\nnot mocks. The full HTTP API surface is reachable — authentication, ticket+CSRF flow,\nAPI tokens, cluster endpoints, storage endpoints, all of it.\n\n### Verified auth flows\n\n| Image     | Installed version | Ticket auth | API-token auth          | Time to healthy |\n|-----------|-------------------|-------------|-------------------------|-----------------|\n| pve-test  | pve-manager 9.2.2 | ✅          | ✅ `…=\u003cuuid\u003e`           | ~12 s           |\n| pbs-test  | proxmox-backup 4.2| ✅          | ✅ `…:\u003cuuid\u003e`           | ~9 s            |\n| pmg-test  | pmg-api 9.x       | ✅          | ❌ (PMG has no token API) | ~10 s          |\n| pdm-test  | proxmox-datacenter-manager 1.0.4 | ✅ | ✅ `…:\u003cuuid\u003e`     | ~6 s            |\n\nThe Rust-family products (PBS, PDM) use a **colon** between token id and value\n(`PBSAPIToken=root@pam!test:\u003cuuid\u003e`) — the Perl-family ones (PVE, PMG) use an\nequals sign (`PVEAPIToken=root@pam!test=\u003cuuid\u003e`). The credentials JSON we write\ninto each container records the correct separator alongside the value, so SDK\ntest code can read `token_header_value` directly without branching on product.\n\n### What does NOT work in these images\n\n- Real backups against a backing datastore (PBS spins up but datastore\n  I/O is limited)\n- Mail filtering (PMG; no real Postfix backend)\n- Cross-node cluster operations (single-node only)\n- API-token auth against PMG (the API surface itself doesn't expose\n  tokens)\n\n### Working KVM and LXC lifecycle in PVE\n\nThe PVE image runs systemd as PID 1 and ships two fixtures so SDK\ntests can drive real start/stop/exec lifecycles, not just config-\nlevel CRUD:\n\n| Fixture | vmid | Source | Host requirement |\n|---------|------|--------|------------------|\n| **VM** `tiny-test` (`qm`) | 100 | [256-byte-vm](https://github.com/client-api/256-byte-vm) v1.0.0 — 1 MiB SeaBIOS-bootable | `--device /dev/kvm` |\n| **CT** `tiny-ct` (`pct`) | 200 | Alpine 3.21 minirootfs                                                   | cgroup v2 on the host |\n\n```bash\n# VMs — needs /dev/kvm\ndocker exec pve-test qm start 100         # boots in \u003c1 s\ndocker exec pve-test qm shutdown 100      # ACPI handler exits cleanly\ndocker exec pve-test qm stop 100          # hard kill\n\n# Containers — needs cgroupv2 host\ndocker exec pve-test pct start 200\ndocker exec pve-test pct exec 200 -- sh -c 'echo \"alpine $(cat /etc/alpine-release)\"'\ndocker exec pve-test pct stop 200\n```\n\nWithout `/dev/kvm` or cgroupv2, the matching config endpoints still\nwork (`qm list`, `pct config`, snapshot/clone config). Only the\n`start` operation hard-fails. WSL2 hosts default to cgroupv1 (LXC\nwon't start); ubuntu-22.04+ GitHub-hosted runners default to cgroupv2\n(everything works).\n\nDisable either fixture at runtime:\n\n```bash\ndocker run … -e PVE_SEED_FIXTURE_VM=0 -e PVE_SEED_FIXTURE_CT=0 …\n```\n\nThis is intentional. The images exist to let SDK client tests exercise the API\nlayer — request shape, response parsing, auth, pagination, error envelopes —\nnot to actually run workloads.\n\n## Quick start (local)\n\nEach product directory ships a self-contained `docker-compose.yml` —\nthe easiest way to spin up one product locally:\n\n```bash\ndocker compose -f pve/docker-compose.yml up -d   # PVE on :8006\ndocker compose -f pbs/docker-compose.yml up -d   # PBS on :8007\ndocker compose -f pmg/docker-compose.yml up -d   # PMG on :8016 (remapped from :8006 to avoid PVE clash)\ndocker compose -f pdm/docker-compose.yml up -d   # PDM on :8443\n```\n\nOverride the image tag without editing the file:\n\n```bash\nPVE_IMAGE=ghcr.io/client-api/proxmox-docker/pve-test:9.2.2 \\\n    docker compose -f pve/docker-compose.yml up -d\n```\n\nThe plain `docker run` equivalent:\n\n```bash\ndocker run -d --rm \\\n    --name pve-test \\\n    --privileged \\\n    --device /dev/fuse \\\n    --device /dev/kvm \\\n    --tmpfs /tmp --tmpfs /run --tmpfs /run/lock \\\n    -p 8006:8006 \\\n    ghcr.io/client-api/proxmox-docker/pve-test:latest\n\n# Wait for readiness\nuntil curl -ks https://localhost:8006/api2/json/version | grep -q version; do sleep 1; done\n\n# Use baked-in credentials\ncurl -k -d 'username=root@pam\u0026password=proxmox123' \\\n    https://localhost:8006/api2/json/access/ticket\n```\n\n`--privileged` is required for two reasons:\n- Proxmox's cluster filesystem (`pmxcfs`) is a FUSE mount.\n- The PVE image runs systemd as PID 1, which needs cgroup access.\n\n`--device /dev/kvm` enables real VM lifecycle (see \"Bonus\" below).\nOmit it if the host lacks KVM — the rest of the API still works.\nThe three `--tmpfs` mounts are systemd's normal expectations for\n`/tmp`, `/run`, `/run/lock` inside a container.\n\n## Baked-in credentials\n\nAll four images ship with the same fixed default credentials. This is intentional\n— these images are for testing, not for production. **Do not expose them on a\npublic network.**\n\n| Field | Value |\n|-------|-------|\n| Root realm user | `root@pam` |\n| Root password   | `proxmox123` |\n| API token name  | `root@pam!test` (PMG: no token API) |\n| API token value | regenerated on every container boot, written to `/run/credentials.json` inside the container |\n\nThe credentials JSON looks like this (PBS example):\n\n```json\n{\n  \"host\": \"pbs-test\",\n  \"port\": \"8007\",\n  \"url\": \"https://pbs-test:8007\",\n  \"user\": \"root@pam\",\n  \"password\": \"proxmox123\",\n  \"realm\": \"pam\",\n  \"token_id\": \"PBSAPIToken=root@pam!test\",\n  \"token_value\": \"c8d10ad4-d4a9-43d5-9df1-5e51cbccc637\",\n  \"token_separator\": \":\",\n  \"token_header_value\": \"PBSAPIToken=root@pam!test:c8d10ad4-d4a9-43d5-9df1-5e51cbccc637\"\n}\n```\n\n`token_header_value` is the exact string to send as `Authorization:` —\ntest code can read it directly, no per-product branching needed.\n\nTo read the token from outside the container:\n\n```bash\ndocker exec pve-test cat /run/credentials.json\n```\n\nOverride the password by setting `PVE_ROOT_PASSWORD`, `PBS_ROOT_PASSWORD`,\n`PMG_ROOT_PASSWORD`, or `PDM_ROOT_PASSWORD` at container start.\n\n## GitHub Actions\n\nFor SDK E2E suites the easiest path is the dedicated companion action,\n[`client-api/proxmox-docker-action`](https://github.com/client-api/proxmox-docker-action):\n\n```yaml\n- uses: docker/login-action@v3\n  with:\n    registry: ghcr.io\n    username: ${{ github.actor }}\n    password: ${{ secrets.GITHUB_TOKEN }}\n\n- uses: client-api/proxmox-docker-action@v1\n  with:\n    product: pve\n    tag: '9.2'\n\n- run: pnpm test:e2e:pve\n  env:\n    NODE_TLS_REJECT_UNAUTHORIZED: '0'\n```\n\nThe action handles the udev rule for `/dev/kvm`, container start +\nhealthcheck wait, exporting credentials as `PROXMOX_*` env vars, and\ncleaning up via a `post:` step. Full input/output reference + matrix\nand lifecycle-gate examples are in the action repo's README.\n\nFor tighter control (custom networking, volume mounts, multiple\ncontainers in one job, …), drop down to a raw service container:\n\n```yaml\njobs:\n  e2e-pve:\n    runs-on: ubuntu-latest\n    services:\n      pve:\n        image: ghcr.io/client-api/proxmox-docker/pve-test:latest\n        options: \u003e-\n          --privileged\n          --device /dev/fuse\n          --device /dev/kvm\n          --tmpfs /tmp\n          --tmpfs /run\n          --tmpfs /run/lock\n          --health-cmd \"/usr/local/sbin/healthcheck.sh\"\n          --health-interval 5s\n          --health-retries 30\n          --health-timeout 5s\n          --health-start-period 60s\n        ports:\n          - 8006:8006\n    steps:\n      - uses: actions/checkout@v4\n      - name: Run SDK E2E\n        env:\n          PVE_HOST: https://localhost:8006\n          PVE_USER: root@pam\n          PVE_PASSWORD: proxmox123\n        run: pnpm test:e2e\n```\n\nSee [`docs/github-actions.md`](./docs/github-actions.md) for the full\nintegration guide including a matrix workflow that exercises all four\nproducts in parallel.\n\n## Repository layout\n\n```\nproxmox-docker/\n├── pve/                Dockerfile, entrypoint, systemd units, docker-compose.yml for Proxmox VE\n├── pbs/                Dockerfile, entrypoint, docker-compose.yml for Proxmox Backup Server\n├── pmg/                Dockerfile, entrypoint, docker-compose.yml for Proxmox Mail Gateway\n├── pdm/                Dockerfile, entrypoint, docker-compose.yml for Proxmox Datacenter Manager\n├── scripts/            Shared helper scripts (repo setup, credential seeding)\n├── docs/               Design notes, GHA integration guide, troubleshooting\n└── .github/workflows/  Build/publish + smoke-test pipelines\n```\n\n## Versioning\n\nTag policy, deprecation rules, and recipes for picking a tag in your\nCI live in [`VERSIONING.md`](./VERSIONING.md). The short version:\n\n- `latest` — most recent stable nightly. Floats freely.\n- `\u003cmajor\u003e.\u003cminor\u003e` (e.g. `9.2`) — floats forward within a series.\n  **Recommended for production CI.**\n- `\u003cversion\u003e` (e.g. `9.2.2`) — immutable, exact upstream package.\n- `dev` — built from the upstream `*-test` apt component for early warning.\n\n## License\n\nApache 2.0 — see [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclient-api%2Fproxmox-docker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclient-api%2Fproxmox-docker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclient-api%2Fproxmox-docker/lists"}