# Deployment

This page covers which files the working directory needs when go-pve-qemu 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/*` | New VMs fail to download the script; the SSH initialization stage aborts and purges the VM |
| `.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 `go-pve-qemu@<tag>.tar.gz` to that release.

```bash
git clone https://github.com/pardnchiu/go-pve-qemu.git /opt/go-pve-qemu
cd /opt/go-pve-qemu
curl -fsSL -o release.tar.gz \
  "https://github.com/pardnchiu/go-pve-qemu/releases/download/<tag>/go-pve-qemu@<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

```ini
[Unit]
Description=go-pve-qemu API
After=network-online.target

[Service]
User=root
WorkingDirectory=/opt/go-pve-qemu
ExecStart=/opt/go-pve-qemu/go-pve-qemu
Restart=on-failure

[Install]
WantedBy=multi-user.target
```

```bash
systemctl daemon-reload
systemctl enable --now go-pve-qemu
journalctl -u go-pve-qemu -f
```

`WorkingDirectory` must point at the directory holding `sh/` and `.env`; `User=root` is required for `qm` / `pvesh` and inter-node SSH.

## Upgrade

1. Get the new binary (rebuild or download the new release)
2. `git pull` to update the `sh/` scripts
3. `systemctl restart go-pve-qemu`

After replacing node hardware, delete `.go_qemu_cpu_type` so the next install re-detects the [CPU Baseline](/cpu-baseline).