Codex
139 lines
3.4 KiB
Markdown
139 lines
3.4 KiB
Markdown
# PVE Cloud Backup
|
|
|
|
Self-hosted Proxmox VE backup manager for uploads to an existing rclone remote such as OneDrive.
|
|
|
|
The application is intentionally small:
|
|
|
|
- FastAPI backend and worker
|
|
- Vue 3 + TypeScript + Tailwind frontend, compiled once into `static/`
|
|
- SQLite for all runtime configuration and state
|
|
- `pvesh` for Proxmox API access
|
|
- `rclone copyto`, `rclone lsjson`, and `rclone deletefile` for exact remote objects
|
|
- systemd services, no Docker
|
|
|
|
## Layout
|
|
|
|
All application files live under:
|
|
|
|
```text
|
|
/opt/pve-cloud-backup/
|
|
backend/
|
|
frontend/
|
|
static/
|
|
data/
|
|
app.db
|
|
logs/
|
|
scripts/
|
|
```
|
|
|
|
The install script copies the two systemd service files to `/etc/systemd/system/`.
|
|
|
|
## Prerequisites
|
|
|
|
Install these on the Proxmox host:
|
|
|
|
- Python 3 with `venv`
|
|
- Node.js and npm for the one-time frontend build
|
|
- `rclone`
|
|
- a preconfigured rclone remote, for example OneDrive or a crypt remote backed by OneDrive
|
|
- working `pvesh` access as the service user
|
|
|
|
The app does not configure rclone. If no remote exists, setup fails until you configure rclone yourself.
|
|
|
|
## Install
|
|
|
|
From the installation directory:
|
|
|
|
```bash
|
|
cd /opt/pve-cloud-backup
|
|
./scripts/install.sh
|
|
```
|
|
|
|
The installer:
|
|
|
|
1. creates required subdirectories,
|
|
2. creates a Python virtual environment,
|
|
3. installs Python dependencies,
|
|
4. builds the Vue frontend into `/opt/pve-cloud-backup/static`,
|
|
5. initializes SQLite migrations,
|
|
6. installs and starts systemd services.
|
|
|
|
Open:
|
|
|
|
```text
|
|
http://<proxmox-host>:8080
|
|
```
|
|
|
|
## Setup
|
|
|
|
On first launch, complete the setup wizard:
|
|
|
|
- Proxmox node
|
|
- Proxmox backup storage
|
|
- local backup directory
|
|
- rclone executable path
|
|
- rclone remote name
|
|
- remote backup path/folder within that remote
|
|
- Discord webhook URL
|
|
- allowed CORS origins
|
|
- default compression
|
|
- default backup mode
|
|
- default retention policy
|
|
- max concurrent backups
|
|
|
|
All settings are stored in SQLite at `/opt/pve-cloud-backup/data/app.db`.
|
|
|
|
## Recovery behavior
|
|
|
|
On worker startup, unfinished records in these states are reconciled:
|
|
|
|
- `pve_running`
|
|
- `local_ready`
|
|
- `uploading`
|
|
- `remote_ready`
|
|
- `local_deleting`
|
|
- `deleting`
|
|
|
|
The worker does not delete unknown local files or remote objects. Local archives are deleted only after upload finishes and the remote object is verified.
|
|
|
|
## Retention cleanup
|
|
|
|
Retention cleanup runs in two places:
|
|
|
|
- immediately after a backup completes for that job;
|
|
- periodically from the worker service, once per hour, so changed rules and day-based expiry are enforced even if no new backup runs.
|
|
|
|
Remote deletion uses exact-object `rclone deletefile` calls for backup records already known in SQLite.
|
|
|
|
## Testing
|
|
|
|
Run backend tests:
|
|
|
|
```bash
|
|
cd /opt/pve-cloud-backup/backend
|
|
./.venv/bin/pytest
|
|
```
|
|
|
|
Run frontend type check and build:
|
|
|
|
```bash
|
|
cd /opt/pve-cloud-backup/frontend
|
|
npm run build
|
|
```
|
|
|
|
Manual integration test for the provided Proxmox test target:
|
|
|
|
```bash
|
|
API_URL=http://127.0.0.1:8080 /opt/pve-cloud-backup/scripts/integration-test-adguard.sh
|
|
```
|
|
|
|
This queues a backup for guest `adguard` / VMID `110` using storage `hitachi` and dump path `/mnt/pve/hitachi/dump`. Expected archive size is approximately 250 MB. The script is explicitly for manual integration testing and does not hardcode these values into normal app behavior.
|
|
|
|
## Uninstall
|
|
|
|
```bash
|
|
/opt/pve-cloud-backup/scripts/uninstall.sh
|
|
```
|
|
|
|
The uninstall script removes and disables systemd services. It leaves `/opt/pve-cloud-backup` intact so `app.db`, logs, and any remaining data are not destroyed accidentally.
|