hippogrief/pobsync
1
0
Fork 0
Code Issues 21 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

(docs) Reframe documentation around Django-first operations

Browse Source 
Update the README to describe pobsync as a Django-first, SQL-backed
service with the control panel as the primary operational interface.

Move CLI examples out of the normal workflow and document them as
maintainer tooling for debugging, services, and migration tasks.
This commit is contained in:
Peter van Arkel
2026-05-19 18:17:43 +02:00
parent b1789d8621
commit 44d821c638
2 changed files with 29 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
README.md
View File

@@ -3,9 +3,10 @@
`pobsync` is a pull-based backup service. It runs on a central backup server and pulls data from remote machines via
rsync over SSH.
The current refactor is SQL-first:
The current refactor is Django-first and SQL-backed:
- Django is the management layer and source of truth.
- The Django control panel is the primary interface for setup and operations.
- The database is the source of truth for hosts, schedules, runs, snapshots, credentials, and retention settings.
- SQLite is the default database; MariaDB is optional.
- Backups use the existing rsync snapshot engine internally.
- Scheduling is handled by a Django scheduler service, not host cron.
@@ -159,6 +160,6 @@ systemctl status pobsync-web pobsync-worker pobsync-scheduler
## Development
Development, Docker, migration helper commands, and architecture notes live in:
Development, Docker, maintainer tooling, and architecture notes live in:
- [docs/development.md](docs/development.md)

74
docs/development.md
View File

@@ -34,58 +34,32 @@ docker compose build web scheduler worker
docker compose run --rm web python manage.py test pobsync_backend --verbosity 2
```
## SQL-First Commands
## Maintainer CLI
The Django UI is the normal operating surface, but the `pobsync` entrypoint remains useful for setup and inspection.
The Django UI is the normal operating surface. The `pobsync` entrypoint and direct `manage.py` commands are kept for
debugging, automated maintenance, and migrations. Prefer using the control panel for day-to-day host configuration,
schedule changes, manual backup queueing, snapshot discovery, retention planning, and SSH credential management.
Create global config:
```
pobsync configure-global --backup-root /mnt/backups/pobsync
```
Create a host config:
```
pobsync configure-host <host> --address <host-or-ip>
```
Run a backup:
```
pobsync backup <host> --prune
```
Create or update a schedule:
```
pobsync schedule <host> --cron "15 2 * * *" --prune
```
Run the scheduler:
```
pobsync scheduler --loop --interval 60
```
Plan or apply retention manually:
```
pobsync retention <host>
pobsync retention <host> --apply --yes --max-delete 10
```
Discover snapshots already present on disk:
```
pobsync discover-snapshots --host <host>
```
The `pobsync` executable is a thin wrapper around Django management commands. Direct Django access is also available:
Useful checks:
```
pobsync django check
python3 manage.py run_pobsync_backup <host> --prune
python3 manage.py showmigrations pobsync_backend
```
Worker and scheduler commands are normally run by systemd services:
```
pobsync worker --loop --interval 15
pobsync scheduler --loop --interval 60
```
One-off maintenance commands are still available when the UI is not the right tool:
```
pobsync backup <host> --dry-run
pobsync discover-snapshots --host <host>
pobsync retention <host>
```
## Migration Helpers
@@ -102,7 +76,8 @@ Export SQL config to legacy runtime YAML for inspection or one-off compatibility
python3 manage.py export_pobsync_configs --prefix /opt/pobsync
```
These commands are migration helpers, not the normal operating model.
These commands are migration helpers, not the normal operating model. After import, review and continue operating from
the Django control panel.
## Docker With SQLite
@@ -158,7 +133,8 @@ sudo scripts/install-systemd --install-extras mariadb
## Current Architecture
The public command surface is Django-first. The old YAML/cron CLI has been retired from the `pobsync` entrypoint.
The public operating surface is Django-first. The CLI is now a maintainer layer around Django management commands and
the old YAML/cron workflow has been retired from the `pobsync` entrypoint.
Discovered snapshots are stored in `SnapshotRecord`, including the base snapshot metadata and a nullable SQL link to the
base record when it is known.