Deployment
Last updated
This page covers which files the working directory needs when QemuRun-pve runs from a release binary or as a systemd service.
Working Directory Requirements
Every relative path resolves against the working directory at startup:
| Path | Purpose | When missing |
|---|---|---|
.env | Environment variables | Logs a warning and falls back to the process environment |
sh/ | Serves OS init scripts under /sh/* | /sh/* returns 404, so curl -fsSL hands an empty script to bash; the pipeline still exits 0 and the VM boots without its init script |
.go_qemu_disabled | Disabled list | The VM list and every state check fail |
.go_qemu_pubkey_admin | Extra admin public keys | Skipped |
.go_qemu_cpu_type | CPU type cache | Generated on the first VM install |
New VMs download their script from
http://<NODE_{MAIN_NODE}>:<PORT>/sh/<os>_<version>.sh, so the VM subnet must reach the main node's PORT.Release Binary
Pushing a
v* tag makes GitHub Actions run go build -o app ./cmd/api with Go 1.25 on ubuntu-latest and attach app packed as QemuRun-pve@<tag>.tar.gz to that release.- git clone https://github.com/pardnchiu/QemuRun-pve.git /opt/QemuRun-pve
- cd /opt/QemuRun-pve
- curl -fsSL -o release.tar.gz \
- "https://github.com/pardnchiu/QemuRun-pve/releases/download/<tag>/QemuRun-pve@<tag>.tar.gz"
- tar -xzf release.tar.gz
- cp .env.example .env
- touch .go_qemu_disabled
- ./app
The clone provides
sh/ and .env.example; the binary does not embed them.systemd Service
- [Unit]
- Description=QemuRun-pve API
- After=network-online.target
- [Service]
- User=root
- WorkingDirectory=/opt/QemuRun-pve
- ExecStart=/opt/QemuRun-pve/QemuRun-pve
- Restart=on-failure
- [Install]
- WantedBy=multi-user.target
- systemctl daemon-reload
- systemctl enable --now QemuRun-pve
- journalctl -u QemuRun-pve -f
The ExecStart line points at the binary:
QemuRun-pve when built from source, app when unpacked from a release. The working directory must point at the directory holding sh/ and .env; User=root is required for qm / pvesh and inter-node SSH.Upgrade
- Get the new binary (rebuild or download the new release)
git pullto update thesh/scriptssystemctl restart QemuRun-pve
After replacing node hardware, delete
.go_qemu_cpu_type so the next install re-detects the CPU Baseline.