catubba/joulenap repository overview

⁠Joulenap

Your Proxmox backup servers sleep. Joulenap wakes them, runs the backups, and tucks them back in.

Joulenap is a small self-hosted web UI + scheduler that runs automated Proxmox VE backups to Proxmox Backup Servers (PBS) that stay powered off most of the time. At the scheduled hour it wakes the backup server (Wake-on-LAN), runs the job, applies retention and garbage collection, powers it back down and notifies you: deduplicated backups on separate hardware, without a second machine running 24/7.

Website: https://joulenap.com⁠
Live demo: https://www.joulenap.com/demo/⁠
Source and docs: https://github.com/Joulenap/joulenap⁠
License: AGPL-3.0

⁠Quick start

One command, no files to download. The container creates its config on first run and you fill it in through the web UI:

mkdir -p /opt/joulenap/data

docker run -d --name joulenap \
  --restart unless-stopped \
  --network host \
  -e TZ=Etc/UTC \
  -v /opt/joulenap/data:/app/data \
  catubba/joulenap:latest
# then open http://<host-ip>:8080

--network host lets Joulenap send the Wake-on-LAN magic packet on your LAN broadcast. The single data directory persists config, run history, logs and the SSH key across updates. Timezone is picked on the first-run screen.

Docker Compose example, a step-by-step Proxmox LXC install and a native no-Docker install: https://github.com/Joulenap/joulenap/blob/main/docs/INSTALL.md⁠

⁠How it works

Joulenap owns the schedule itself, so nothing on the Proxmox host is modified. It talks to every PVE and PBS through their APIs (one scoped token per device) and uses a single SSH command only for the power-off, which has no API.

You describe your setup as routes: which Proxmox hosts back up to which backup server, on what schedule, with what retention. A route can fan several PVE hosts into one PBS, or copy one PBS to another for an off-site second copy. Joulenap wakes and sleeps every box each route touches, in the right order, and a box needed by two consecutive runs is woken once.

⁠Features

• Routes over any number of Proxmox hosts and backup servers, including PBS to PBS sync (pull or push)
• A schedule per route with its own retention, guest selection and options, plus a global pause switch
• Wake-on-LAN with readiness wait, retries and timeout; always-on boxes supported too
• Back up all guests of a host (new ones included automatically) or an explicit include list
• Retention (last/daily/weekly/monthly/yearly), optional garbage collection and verification after a run
• External schedules: let PVE/PBS run their own jobs, Joulenap just wakes the box, watches the tasks and powers it off when they go quiet
• Notifications via Apprise, Telegram, ntfy, Discord, email, on success and/or failure, per route
• Live log viewer, run history with a per-step timeline, live PVE/PBS task output, manual runs, stop mid-run
• Built-in config.yaml editor, opt-in update check
• Integrations: backup status for Homepage, Homarr, Dashy and Glance, plus a Prometheus /metrics endpoint
• Multi-language UI, login-protected, works on a phone

⁠Tags

• latest: the most recent stable release
• x.y.z: a specific release, pinned

Guided wizards add each PVE or PBS: connect to the host, discover the backup servers it already knows about, detect interface and MAC, and provision the API token and SSH key. Root credentials are used only during that step and never stored.

⁠Links

• Changelog and releases: https://github.com/Joulenap/joulenap/releases⁠
• Issues: https://github.com/Joulenap/joulenap/issues⁠
• Architecture and API: https://github.com/Joulenap/joulenap/blob/main/docs/ARCHITECTURE.md⁠

Not affiliated with Proxmox Server Solutions GmbH.