jusbackup — Incremental System Backup & Restore to Google Drive

Facts

Fact	Value
Status	active
Hosting platform	other
Repository	https://github.com/meta4m/jusbackup
Tech stack	language: bash, language: python, backup_tool: restic, transfer: rclone, storage: google-drive, scheduler: systemd-timer, search: ripgrep, notifications: libnotify, platform: linux-mint-xfce
Tags	backup, restore, restic, rclone, google-drive, encryption, cli, systemd, disaster-recovery
Last audited	2026-09-15
Upstream dependencies	None declared
Downstream dependencies	None declared

Secrets manifest

Key names and metadata only. Encrypted records are available in this project’s vault below.

Key	Description	Environments	Required
`RESTIC_MASTER_PASSWORD`	Restic repository master password (contents of the gitignored .restic_pass file, chmod 600) — AES-256 zero-knowledge encryption key for the Google Drive backup repository; without it no backup data can be decrypted	production	Yes
`GOOGLE_OAUTH_CLIENT_ID`	Personal Google Cloud OAuth Client ID configured into the rclone ‘gdrive’ remote, providing a private 1,000,000 requests/day Drive API quota (optional — rclone falls back to its public client ID)	production	No
`GOOGLE_OAUTH_CLIENT_SECRET`	Google Cloud OAuth Client Secret paired with the Client ID for the rclone gdrive remote (displayed only once at creation in Google Cloud Console)	production	No

Overview

Project Overview: jusbackup

1. Executive Summary

Mission: A low-resource, zero-knowledge, incremental backup & restore CLI — Restic snapshots (AES-256, block-level dedup) of a Linux Mint XFCE laptop plus one-time Windows partition archival, shipped through Rclone to a personal Google Drive, with a single multi-profile bash CLI (jusbackup).
Target Audience: The operator’s own machines — an HP ProBook running Linux Mint XFCE (snapshot tag linux-mint-probook) and Windows partitions mounted under /media/iu/… (tag windows7-probook). The README notes it works on any Debian/Ubuntu system.
Primary Maintainer: The operator (meta4m) — solo developer; authored all 36 commits (2026-08-01 → 2026-09-14).

2. Current Status & Roadmap

Lifecycle State: active — latest commit 2026-09-14 (exclude-rule hardening: *.so.*, AI engines/models, archives) and the tool runs in production weekly via a systemd user timer (Mondays 00:00 PKT per README).
Ongoing work: iterative refinement, not new features — the 36 commits tune exclusions, retention, terminal progress display, rclone rate-limit handling, and find/search scoping. No issue tracker, roadmap, or TODOs exist in the repo.

3. Core Capabilities

All-in-one CLI (backup.sh, symlinked as ~/.local/bin/jusbackup): default Linux backup, windows archival profile, snapshots, tag, find [--latest], search [--latest], restore [dir] [path], mount, help.
Zero-knowledge encryption & dedup: Restic AES-256 with the gitignored .restic_pass (chmod 600); --pack-size=32; --one-file-system skips remote mounts; per the README, without the password no one can decrypt the Drive repository.
Low system impact: nice -n 19 + ionice -c 3, ~30–50MB RAM (README claim), flock per-profile lock prevents overlapping runs.
Retention: restic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 12 --prune on the Linux profile only — the Windows archival snapshot is never pruned.
Personal Google Drive transport: rclone gdrive remote on a private Google Cloud OAuth client (README: 1,000,000 requests/day quota, zero 403 rate-limit errors); TPS limit 10 + burst 5, 10 retries, 32M chunks; repository auto-created at Drive folder LinuxMintBackup.
Search & recovery: find matches exact filename patterns across all snapshots (or --latest Linux snapshot); search streams content matches (ripgrep, grep fallback) over a temporary --no-lock FUSE mount; mount exposes the repo at ~/backup_mount for drag-and-drop recovery in Thunar.
Ops hygiene: backup.log auto-truncated past 1MB, python3 stream filter strips rclone JSON error payloads, XFCE notify-send notifications on success/failure.
Coverage: sources.txt backs up /data/projects — the workspace hosting 2brain and the other cataloged repos (ai-job-mvp, baghbaan, gemini-adapter-worker, provider-ping, scrabbler, scrabble-scoresheet, vbot-cf) — so the entire 2Brain catalog is inside the weekly snapshot scope.

4. Key References

Repository: meta4m/jusbackup
Production URL: none — a personal CLI tool run from the operator’s laptop, not a deployed web service.
Architecture Docs: architecture.md · Deployment Guide: deployment.md

Architecture

Architecture & System Design: jusbackup

1. System Topology

graph TD
    Timer["systemd user timer jusbackup.timer<br/>weekly · Mon 00:00 PKT (README)"] -->|triggers| CLI["jusbackup → backup.sh<br/>subcommand dispatcher + profiles"]
    Operator["Operator terminal"] --> CLI
    CLI --> Cfg["config.env<br/>sources*.txt · exclude*.txt"]
    CLI --> Pass[".restic_pass (chmod 600, gitignored)"]
    CLI -->|"nice -n 19 · ionice -c 3"| Restic["restic backup · forget --prune<br/>AES-256 · dedup · --pack-size=32"]
    Restic -->|"rclone:gdrive:LinuxMintBackup"| Rclone["rclone remote 'gdrive'<br/>personal Google OAuth client · TPS 10"]
    Rclone --> Drive[("Google Drive vault<br/>jusbackups@gmail.com")]
    CLI --> Search["find / search<br/>temp FUSE mount + ripgrep"]
    Search --> Restic
    CLI --> Ops["backup.log (1MB cap)<br/>python3 JSON-error filter · notify-send"]

2. Core Components & Subsystems

backup.sh (345 lines) — the entire product: case $MODE dispatch for snapshots|list, tag, find, search, mount, restore, windows|win, default|linux|backup, help. The windows profile swaps in sources-windows.txt / exclude-windows.txt and tag windows7-probook.
config.env: rclone remote (gdrive) and Drive folder (LinuxMintBackup), custom restic binary path (/home/iu/.local/bin/restic), password/log file paths, and rclone performance exports (RCLONE_TPSLIMIT=10, burst 5, low-level + normal retries ×10, RCLONE_DRIVE_CHUNK_SIZE=32M, PAGESIZE=50).
Profiles: sources.txt (Documents, Pictures, /data/projects, ~/.config) with exclude.txt (build dirs, caches, node_modules/, .wrangler/, AI engines/models, *.so*, disk images, archives); the Windows variant adds AppData / pagefile / Recycle-Bin skips.
filter_clean_logs: inline python3 -u stream filter that drops multi-line rclone “Details:” JSON payloads (e.g. rateLimitExceeded) while preserving base ERROR lines.
Safeguards: flock -n on /tmp/jusbackup-<profile>.lock; TTY-aware output (live single-line restic status interactively, filtered log when run by systemd); mandatory password-file check with notify-send on failure.

3. Data Flow & Storage Contracts

No database, no app state — local artifacts only: backup.log (auto-truncated to the last 2,000 lines past 1MB), /tmp/jusbackup-<profile>.lock, and the gitignored .restic_pass.
Remote contract: one restic repository at rclone:gdrive:LinuxMintBackup, auto-created on first run; snapshots tagged linux-mint-probook (weekly, pruned 7d/4w/12m) or windows7-probook (archival, never pruned).
Encryption: AES-256 zero-knowledge — restic encrypts and dedups locally; Google Drive holds opaque packs only.
search data path: restic mount --no-lock into a mktemp dir → ripgrep (grep fallback) over snapshots/ or tags/linux-mint-probook/latest, binary/media globs excluded, results streamed and path-stripped; the FUSE mount is cleaned up via an EXIT trap.
Coverage: /data/projects in sources.txt pulls in the 2Brain workspace (2brain) and every cataloged repo living there, so catalog code is protected by the same weekly snapshot.

4. Architectural Decision Records (ADRs)

ADR-01: Restic over Rclone to a personal Google Drive

Context: Off-site, encrypted, deduplicated backup with no server to run and consumer-grade storage.
Decision: a restic repository accessed through an rclone gdrive remote backed by a private Google Cloud OAuth client (README: 1M requests/day quota, zero 403s).
Consequences: zero-knowledge encryption + dedup on cheap storage; disaster recovery needs only two binaries and three secrets (restic password, Google account, OAuth client pair) on any OS.

ADR-02: One bash script with subcommands, not an application

Context: the tool must run on a low-resource XFCE laptop, be auditable at a glance, and be restorable onto a bare machine.
Decision: a single backup.sh driven by plain-text profile files, installed via a ~/.local/bin symlink; behavior splits into two tagged profiles rather than a config UI.
Consequences: no runtime dependencies beyond restic/rclone/python3/FUSE; no cross-platform CLI (Windows restores use raw restic.exe commands from RESTORE_GUIDE.md), and the systemd unit files referenced by the setup docs are absent from the repo.

ADR-03: Asymmetric retention per profile

Context: the Windows profile is a one-time archival snapshot; the Linux profile recurs weekly.
Decision: forget --prune retention (7 daily / 4 weekly / 12 monthly) runs only on the default Linux profile.
Consequences: the weekly snapshot set stays bounded; the archival snapshot is preserved verbatim but would grow unbounded if the profile were ever re-run.

ADR-04: Invisible backups — lowest priority + personal API quota

Context: backups must not disturb daily work, and rclone’s public OAuth client rate-limits (403s) break large transfers.
Decision: run under nice -n 19 + ionice -c 3, filter rate-limit noise from logs, and use a personal Google Cloud client with tuned TPS/chunk settings.
Consequences: backups are slow but non-intrusive; the client secret is shown only once by Google Cloud Console and must be saved immediately.

Deployment

Deployment & Operational Runbook: jusbackup

1. Hosting & Environments

Environment	Platform	URL / Endpoint	Auto-Deploy Branch
Production	Operator’s Linux Mint XFCE laptop (HP ProBook) — systemd user timer	N/A (local CLI; remote vault = Google Drive `LinuxMintBackup`)	none — no CI/CD; manual `git pull` + symlink
Windows archival source	Windows partitions mounted at `/media/iu/…` on the same laptop	one-time `jusbackup windows`	N/A
Local dev	same machine, manual `jusbackup` invocation	N/A	N/A

No GitHub workflows exist; “deployment” means installing the CLI on a machine and enabling the weekly timer.

2. Prerequisites & Toolchain

Debian/Ubuntu/Mint Linux; bash; restic (config.env points to a manually installed /home/iu/.local/bin/restic; apt install restic also works); rclone; python3 (log filter); ripgrep (optional, for search); FUSE (restic mount, fusermount -u); notify-send (optional notifications); systemd (weekly timer).

3. Local Development Setup

git clone https://github.com/meta4m/jusbackup.git ~/projects/jusbackup
# restore .restic_pass into ~/projects/jusbackup/ (chmod 600 — gitignored, never committed)
rclone config                 # create remote 'gdrive' with your Client ID/Secret
ln -sf ~/projects/jusbackup/backup.sh ~/.local/bin/jusbackup
jusbackup snapshots           # verify the repository is reachable
# weekly automation (per README):
mkdir -p ~/.config/systemd/user
cp jusbackup.service jusbackup.timer ~/.config/systemd/user/
systemctl --user daemon-reload && systemctl --user enable --now jusbackup.timer

Flag: jusbackup.service and jusbackup.timer are referenced by the README/RESTORE_GUIDE setup steps but are not present in the repository — they must be authored by hand (timer schedule: Mondays 00:00 PKT per README).

4. Environment & Secrets Provisioning

Refer to spec.yml — manifest keys: RESTIC_MASTER_PASSWORD, GOOGLE_OAUTH_CLIENT_ID, GOOGLE_OAUTH_CLIENT_SECRET. Retrieve ciphertext from 2Brain vault and decrypt locally into .env.local.

RESTIC_MASTER_PASSWORD → write the plaintext into ~/projects/jusbackup/.restic_pass (chmod 600).
GOOGLE_OAUTH_CLIENT_ID / GOOGLE_OAUTH_CLIENT_SECRET → entered during rclone config for the gdrive remote (kept in rclone’s own config, not env).
The Google account holding the Drive vault (jusbackups@gmail.com per README) is also a critical DR credential — its login lives in the operator’s password manager, outside this manifest.
Non-secret knobs in config.env: RCLONE_REMOTE, GDRIVE_FOLDER, RESTIC_BIN, log paths, rclone performance exports.

5. Deployment Commands

jusbackup                     # weekly Linux backup (tag linux-mint-probook) + prune
jusbackup windows             # one-time Windows archival (tag windows7-probook)
jusbackup snapshots           # list snapshots
systemctl --user list-timers jusbackup.timer   # check the schedule
cat ~/projects/jusbackup/backup.log            # inspect the log

6. Verification & Health Checks

After any change: jusbackup snapshots (repository reachable), then a small partial restore — e.g. jusbackup restore /tmp/verify /data/projects/2Brain — to prove the 2brain workspace round-trips.
Timer health: systemctl --user list-timers jusbackup.timer; failures surface as critical notify-send desktop notifications plus ERROR lines in backup.log.
Note: the code repositories for nextrole and scorepad live outside /data/projects (checked 2026-09-15) — their catalog docs are covered via the 2Brain workspace, but the code itself falls outside the default backup sources; verify their coverage separately.

7. Incident Response & Rollback

Failed run: check backup.log (auto-capped at 1MB) — the python filter preserves base ERROR lines even when rclone JSON payloads are stripped; fix the cause and rerun manually (flock prevents overlap).
Missing .restic_pass: the script exits 1 with a critical notification — restore the file from the password manager/vault before anything else.
Full disaster recovery: install restic + rclone on any OS, rclone config the gdrive remote, then jusbackup restore (or raw restic.exe -r rclone:gdrive:LinuxMintBackup restore latest --target … on Windows) — see RESTORE_GUIDE.md’s 3-secret checklist.
Tool rollback: git checkout <previous-commit> — snapshots are immutable, so reverting the script never touches backup data.

Project vault

Cloudflare Access authorization and your passphrase are required to retrieve and decrypt stored values.

Client-Side Encrypted Secret Vault

Zero-knowledge architecture. Secrets are encrypted client-side using Web Crypto AES-256-GCM before leaving this browser tab. Edge databases store only ciphertext, IV, and salt.

Vault Passphrase (PBKDF2-SHA256, 100,000 iterations):

Encrypted Records for `jusbackup` (0)

Encrypted records have not been loaded.