django-offsite-backup 0.1.0__py3-none-any.whl

django_offsite_backup-0.1.0.dist-info/METADATA

@@ -0,0 +1,133 @@
+Metadata-Version: 2.5
+Name: django-offsite-backup
+Version: 0.1.0
+Summary: Encrypted, immutable off-site backups of a Django project's databases, media and deployment configuration
+Project-URL: Homepage, https://github.com/CorneiZeR/django-offsite-backup
+Project-URL: Documentation, https://corneizer.github.io/django-offsite-backup/
+Project-URL: Changelog, https://github.com/CorneiZeR/django-offsite-backup/blob/master/CHANGELOG.md
+Project-URL: Issues, https://github.com/CorneiZeR/django-offsite-backup/issues
+Project-URL: Repository, https://github.com/CorneiZeR/django-offsite-backup
+Author-email: Oleksii Kolosiuk <kolosyuk1@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: age,backup,django,encryption,object-lock,postgres,retention,s3,telegram
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Framework :: Django :: 6.1
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: System :: Archiving :: Backup
+Classifier: Typing :: Typed
+Requires-Python: <3.15,>=3.10
+Requires-Dist: django>=5.2
+Provides-Extra: aiogram
+Requires-Dist: django-aiogram>=5.2; extra == 'aiogram'
+Provides-Extra: all
+Requires-Dist: boto3>=1.34; extra == 'all'
+Requires-Dist: django-aiogram>=5.2; extra == 'all'
+Requires-Dist: httpx2>=2.0; extra == 'all'
+Provides-Extra: s3
+Requires-Dist: boto3>=1.34; extra == 's3'
+Provides-Extra: telegram
+Requires-Dist: httpx2>=2.0; extra == 'telegram'
+Description-Content-Type: text/markdown
+
+# django-offsite-backup
+
+[![CI](https://github.com/CorneiZeR/django-offsite-backup/actions/workflows/ci.yml/badge.svg)](https://github.com/CorneiZeR/django-offsite-backup/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/django-offsite-backup.svg)](https://pypi.org/project/django-offsite-backup/)
+[![Python](https://img.shields.io/pypi/pyversions/django-offsite-backup.svg)](https://pypi.org/project/django-offsite-backup/)
+
+Off-site backups of a Django project's **databases, media and deployment configuration**:
+compressed, encrypted to a public key the server holds (so the server can write a backup
+and cannot read one), uploaded to S3 with **Object Lock COMPLIANCE** read back on every
+object, and rotated by **whole nights** — never by age alone, never by object count.
+
+- PostgreSQL (one database, a list, or a list computed at run time), plain or custom format
+- media from a directory, a Docker volume or an S3 bucket, in volumes of whole files
+- the deployment directory plus the environment rebuilt from a list of variable names
+- `age` encryption to one or more recipients; `zstd` compression before it
+- a pass before every deploy without media (fast, and never mistaken for a night)
+- a once-per-night guard, and a morning check that notices the night that never ran
+- every outcome said in Telegram (or through django-aiogram, or a log), in one glanceable format
+- restore that downloads, decrypts, verifies — and, on request, loads a database
+- system checks that refuse a half-configured machine by name and a bucket without a lock
+
+Every backend is a dotted path in settings and imported only when named; each driver is an
+extra. A base install pulls Django and nothing else.
+
+## 30-second setup
+
+```shell
+pip install "django-offsite-backup[s3,telegram]"
+```
+
+```python
+import os
+
+INSTALLED_APPS = [..., 'offsite_backup']
+
+OFFSITE_BACKUP = {
+    'PREFIX': 'acme/prod',
+    'ENV': 'prod',
+    'STORE': {
+        'BACKEND': 'offsite_backup.stores.s3.S3Store',
+        'ENDPOINT_URL': os.environ.get('BACKUP_S3_ENDPOINT_URL', ''),
+        'BUCKET': os.environ.get('BACKUP_S3_BUCKET', ''),
+        'ACCESS_KEY': os.environ.get('BACKUP_S3_ACCESS_KEY', ''),
+        'SECRET_KEY': os.environ.get('BACKUP_S3_SECRET_KEY', ''),
+        'LOCK_DAYS': 13,
+    },
+    'ENCRYPTION': {
+        'BACKEND': 'offsite_backup.encryption.age_cli.AgeCli',
+        'RECIPIENTS': [os.environ.get('BACKUP_AGE_RECIPIENT', '')],
+    },
+    'DATABASES': {'BACKEND': 'offsite_backup.databases.postgres.PostgresSource'},
+    'MEDIA': [{'BACKEND': 'offsite_backup.media.filesystem.DirectorySource'}],
+    'CONFIG': {'BACKEND': 'offsite_backup.config.paths.PathsSource', 'PATHS': ['/app/deploy']},
+    'RETENTION': {'KEEP_NIGHTS': 14},
+    'NOTIFY': [
+        {
+            'BACKEND': 'offsite_backup.notifiers.telegram.TelegramNotifier',
+            'TOKEN': os.environ.get('BACKUP_TG_TOKEN', ''),
+            'CHAT_ID': os.environ.get('BACKUP_TG_CHAT_ID', ''),
+        }
+    ],
+}
+```
+
+With every credential empty (a development machine) backups are **off** and the commands
+say "nothing to do". With some set and some missing, `manage.py check` names each one.
+
+```shell
+python manage.py check --deploy                                  # bucket lock, pg_dump version
+python manage.py backup_offsite                                  # a pass now
+python manage.py backup_offsite --without-media --reason deploy  # before a migration
+python manage.py backup_check                                    # the morning check
+python manage.py backup_list
+python manage.py backup_restore --stamp latest --identity key.txt --into ./restore
+```
+
+The image needs `pg_dump` (at least the server's major), `zstd` and `age`. The bucket must be
+created **with Object Lock** and a default COMPLIANCE rule of `LOCK_DAYS` days.
+
+## Documentation
+
+**<https://corneizer.github.io/django-offsite-backup/>** — installation, every setting,
+S3 providers, retention and locks, restore drills, the security model, troubleshooting by
+check code, and a page for AI assistants wiring the package into a project.
+
+## License
+
+MIT

django_offsite_backup-0.1.0.dist-info/RECORD

@@ -0,0 +1,59 @@
+offsite_backup/__init__.py,sha256=e9ixtQw21GQzoCL7gjQwcdWWiwZ5vLByNQUJSB_IE8s,1664
+offsite_backup/apps.py,sha256=lKvu2XJPJV5UO6HVK16FqgRZgZ15s1uIpjqKHTZk-BQ,596
+offsite_backup/backend.py,sha256=LbfDbIUY8_twsYuvZq_7GXbfMannffWxwLathQDwZnc,1971
+offsite_backup/check.py,sha256=HQooAd-RSGPeBUGPTMDlPYWg7mm5oWFwQsW8mrOZMqs,3236
+offsite_backup/checks.py,sha256=FM8IqjkyG11019sJohYKFHlwGvtzo59XyMej-Oi_ys8,5809
+offsite_backup/conf.py,sha256=jgCoS4yMMZJlDZr36GhkonAfgL2YVlNAPeDWtK5MEy0,7878
+offsite_backup/exceptions.py,sha256=iZRM9R_mOIYxUHSdI9c9FLlenRxl5PyBvxEmHEJEwUo,1284
+offsite_backup/guard.py,sha256=IBIRNGgsn2W7DL5L96GcCSji77gtGSWcxU1knKlvckk,2356
+offsite_backup/naming.py,sha256=-qy6gcA0g2tHIs8KPe6mEbG60elIH3g8Xi7JLZmGUZA,3514
+offsite_backup/notify.py,sha256=BFSYqGmkYdaFN3CJoYGnMs5Ozv4Z0ZpyntWSHWV6XEk,3659
+offsite_backup/outcome.py,sha256=thOBkcJQQ6ZtBJQgVI1JsCCTRbPz_Kis81pjcfHqy5k,1416
+offsite_backup/pass_.py,sha256=jd2fyNryi0NjLs1aiF9BIiyUezsAq0G3tY4YDjR-fp4,11396
+offsite_backup/pipeline.py,sha256=CMe3MD3u_mj-OEB3ou0aqa7VjoAkDmUNJDHsHwvuaFU,5305
+offsite_backup/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+offsite_backup/registry.py,sha256=7bjb8gnjv6PJLcnWyqUF5tZjqJDcMANgnsJq294hlNw,2940
+offsite_backup/restore.py,sha256=KpQjdcsNQJhvPVGoyiGKXgW9te4tndZd3nyZkBW1_pc,7369
+offsite_backup/rotation.py,sha256=mxIwN6wt1wM6QmMGJoMbkGXTWKi39u8owXAVZMLIGqI,3791
+offsite_backup/sealing.py,sha256=UUoa23kUa9A2YIZM2O9TDvnDBh0DMP1CiiH-SWySgP0,830
+offsite_backup/config/__init__.py,sha256=YRGYdWHVH0ATCi7cGPX_bBOI7J-V8gb2ehP5WEPmfLs,45
+offsite_backup/config/base.py,sha256=EzwrtIVKwYYWvYVt9Kv9-AYPApAUmxkD8Awx-ktQlvA,602
+offsite_backup/config/paths.py,sha256=9mp0H_CWIZDFbKBp4gr61vTl3mfaHyz01VsQ8iEXt2Q,5669
+offsite_backup/databases/__init__.py,sha256=pUEGQ3Xa36XdqEc6OZ6gD1evtXgbPi4-FO1KdgkFAX4,48
+offsite_backup/databases/base.py,sha256=sKL9S4bGA6OWVjhKr6_4CR3hjLDE9-SmoOWJI3WI4Tg,1111
+offsite_backup/databases/postgres.py,sha256=02UvUu6FkDQw_FMEZbJ9IT-q5FQPhuEubfKqzRTu9uk,8515
+offsite_backup/encryption/__init__.py,sha256=i9umI8tcO1M87YcXKiomR6T_P8FUAN7aXfRq07Afzck,49
+offsite_backup/encryption/age_cli.py,sha256=dn04GDSi8MF9ndALZTIKBtVKaV2rrDxZDHd2PCJaCXI,2235
+offsite_backup/encryption/base.py,sha256=gBiLHuE3DZcDelYfTfegxP5oWZSvl_8MDlIbydg48Ek,680
+offsite_backup/management/__init__.py,sha256=vcqDX6mxQ9kPOJernLPiYVbh_fT6_XGStBUxXfEG-fA,49
+offsite_backup/management/commands/__init__.py,sha256=kAx43lKcH5YmrRyekdKsKoJIUpPO2Y8p3RV-raqGKtI,58
+offsite_backup/management/commands/backup_check.py,sha256=M5nJgx0M3Da9-juj_xNLDhr2RKJU3OXfyslZ4pOCzjU,1063
+offsite_backup/management/commands/backup_list.py,sha256=96C6qlLPF_jwO40GC1RZoN0L8FTpnRoTwT_QbnLErQQ,4011
+offsite_backup/management/commands/backup_offsite.py,sha256=oLH8g1ZG4dX6Kfl7eOhuTwQvTE91i6n-vMOO-bUUH_A,2055
+offsite_backup/management/commands/backup_restore.py,sha256=WN7CT4LH9lvtuWHr3qF6pFFaoFKUzMdOwvIwH51sCHQ,3119
+offsite_backup/media/__init__.py,sha256=LltKrhhcIU_9bt_TmzOpGEBcdrlgF_fIZCfHlKV3EnA,44
+offsite_backup/media/base.py,sha256=5ipIwQv9r_NLA07gbFG-F2mpZsi8gCSvoHKCRWRyniE,5050
+offsite_backup/media/filesystem.py,sha256=-EmIK1hDLEV9ms5knWcbKeob7Z4WNJi12_7RbcWxiGo,3097
+offsite_backup/media/s3.py,sha256=cp2QHJtoMptaRvJ--9vYvr3jF_-oqJK4C4kpMrmmcOA,1902
+offsite_backup/messages/__init__.py,sha256=C6yxHrUo_LOdnHXsTMAudTHD1y4E2vMlGO7pLmF6zTI,47
+offsite_backup/messages/default.py,sha256=RuKQQqv4KF8xHuNDGwhCpSm3YwsCAYffF4EQ_l98KzI,4438
+offsite_backup/notifiers/__init__.py,sha256=0X7uJIL1kXIjLGV1YKk7NSrpXvnj4TVYBozUsXRN8hI,48
+offsite_backup/notifiers/base.py,sha256=YUVreA0b5PIUIBZoY2A9dYxduD92C66xNCLvMPjDoAM,540
+offsite_backup/notifiers/django_aiogram.py,sha256=oa0X3HhLYFczX1rHrECwQ0NEvNiBpC2EP5XWJrfeW-k,1824
+offsite_backup/notifiers/log.py,sha256=dRepc9FAJ2yZpopGtGzZUavYxCJvWZ5A9s-45dWPs98,710
+offsite_backup/notifiers/telegram.py,sha256=exOBSZiS-GJwExmuPI3L8rFufobi7eqpwSbo9nYlFOU,3216
+offsite_backup/schedule/__init__.py,sha256=5YyZvDkluM_WYztCiEtiwJra4tE_odFo_thvdpApIMk,47
+offsite_backup/schedule/celery.py,sha256=g682IvRkzqRol1vlZ-826P3ai8wN6y9YiUV9gi99T_w,1651
+offsite_backup/schedule/taskiq.py,sha256=XX1LzeMcb40qNTXTCFmFlZDnWnxpbxjKqyP3S66nzgk,1551
+offsite_backup/stores/__init__.py,sha256=v0CNT_EjbIcw1q6QxV0DHUmzrWuxe3zrkihRkFLIhXU,45
+offsite_backup/stores/base.py,sha256=vCFJ-Ovp-zTX9SS4Op21TYlZI6ZSHbQyjJ3eNqkmOTg,2200
+offsite_backup/stores/filesystem.py,sha256=yn7g2itSs5T4xuDD417LF8SINP3msc77SNs7ciFeUZU,3392
+offsite_backup/stores/s3.py,sha256=0-OBfiOOEYwdeL5idHbfCqfhsC7CpD7Hy4SeitVwSOA,12374
+offsite_backup/testing/__init__.py,sha256=SSR2863QBQyi-YeBNBxAUUT3NXHxSfY07Ws24PeiZNY,2826
+offsite_backup/testing/fake_s3.py,sha256=VToHI0FuAZr45lZJisCJCwHl6_T-ga0KcyYCwL9a8j0,11693
+offsite_backup/testing/pytest_plugin.py,sha256=n8Q7SAUNH0HRNUkd26tIqTbwVoaIGFXMgjq9pYzJqCs,848
+django_offsite_backup-0.1.0.dist-info/METADATA,sha256=MiQIxMZUMh15qyJ2dm8pIm7YMM-ktk7eZitHhmbXO4I,6128
+django_offsite_backup-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+django_offsite_backup-0.1.0.dist-info/entry_points.txt,sha256=zuksgsw_Q6ik9qa7T6mHP_YJ4W8htU-pn7vjssnxigs,65
+django_offsite_backup-0.1.0.dist-info/licenses/LICENSE,sha256=tXJD1E9WjBwUT_uLFM0IuzULlvjAF40iDz-1HbCUfKU,1073
+django_offsite_backup-0.1.0.dist-info/RECORD,,

django_offsite_backup-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

django_offsite_backup-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[pytest11]
+offsite_backup = offsite_backup.testing.pytest_plugin

django_offsite_backup-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oleksii Kolosiuk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

offsite_backup/__init__.py

@@ -0,0 +1,52 @@
+"""Encrypted, immutable off-site backups for Django projects.
+
+Importing the package loads nothing but Django's settings machinery: every backend,
+driver and the pass itself are imported when first used (PEP 562 ``__getattr__``).
+"""
+
+from typing import TYPE_CHECKING, Any
+
+__version__ = '0.1.0'
+
+__all__ = (
+    'BackupError',
+    'NotConfiguredError',
+    '__version__',
+    'back_up_database',
+    'check_last_night',
+    'keep_apart',
+    'restore_database',
+    'run',
+    'run_nightly',
+)
+
+_EXPORTS = {
+    'run': 'offsite_backup.pass_',
+    'back_up_database': 'offsite_backup.pass_',
+    'keep_apart': 'offsite_backup.pass_',
+    'run_nightly': 'offsite_backup.guard',
+    'check_last_night': 'offsite_backup.check',
+    'restore_database': 'offsite_backup.restore',
+    'BackupError': 'offsite_backup.exceptions',
+    'NotConfiguredError': 'offsite_backup.exceptions',
+}
+
+if TYPE_CHECKING:
+    from offsite_backup.check import check_last_night
+    from offsite_backup.exceptions import BackupError, NotConfiguredError
+    from offsite_backup.guard import run_nightly
+    from offsite_backup.pass_ import back_up_database, keep_apart, run
+    from offsite_backup.restore import restore_database
+
+
+def __getattr__(name: str) -> Any:
+    """Resolve a public name on first use, so ``import offsite_backup`` stays cheap."""
+    module = _EXPORTS.get(name)
+    if module is None:
+        msg = f'module {__name__!r} has no attribute {name!r}'
+        raise AttributeError(msg)
+    import importlib  # noqa: PLC0415 - only when an export is first asked for
+
+    value = getattr(importlib.import_module(module), name)
+    globals()[name] = value
+    return value

offsite_backup/apps.py

@@ -0,0 +1,19 @@
+"""The Django app: registers the system checks and imports nothing else."""
+
+from django.apps import AppConfig
+
+__all__ = ('OffsiteBackupConfig',)
+
+
+class OffsiteBackupConfig(AppConfig):
+    """Registers the checks; every backend stays unimported until a pass needs it."""
+
+    name = 'offsite_backup'
+    verbose_name = 'Off-site backup'
+    default_auto_field = 'django.db.models.BigAutoField'
+
+    def ready(self) -> None:
+        """Register the system checks."""
+        from offsite_backup import checks  # noqa: PLC0415 - registration is the import's effect
+
+        checks.register_all()

offsite_backup/backend.py

@@ -0,0 +1,48 @@
+"""What every pluggable backend shares: its options block, its requirements, its checks."""
+
+import shutil
+from collections.abc import Mapping
+from typing import Any, ClassVar
+
+from django.core import checks
+
+__all__ = ('Backend',)
+
+
+class Backend:
+    """A backend built from its own settings block (``BACKEND`` plus options)."""
+
+    #: options that must be non-empty once backups are on; E001 names each one missing
+    REQUIRED: ClassVar[tuple[str, ...]] = ()
+    #: options whose presence means "this machine is meant to back up" (see ``conf.enabled``)
+    SIGNALS: ClassVar[tuple[str, ...]] = ()
+    #: executables this backend runs; E003 names each one absent from PATH
+    BINARIES: ClassVar[tuple[str, ...]] = ()
+    #: a backend that cannot reach the network may run under a test suite (see ``testing``)
+    REACHES_NETWORK: ClassVar[bool] = False
+
+    def __init__(self, options: Mapping[str, Any], *, label: str = '') -> None:
+        """Keep the options block and the label checks and errors name it by."""
+        self.options = dict(options)
+        self.label = label or type(self).__name__
+
+    def option(self, name: str, default: Any = None) -> Any:
+        """One option, with ``default`` for absent *and* for ``None``."""
+        value = self.options.get(name)
+        return default if value is None else value
+
+    def check(self) -> list[checks.CheckMessage]:
+        """Local, offline checks: binaries present, options well formed."""
+        return [
+            checks.Error(
+                f'{self.label} runs `{binary}`, which is not on PATH.',
+                hint=f'Install {binary} in the image that runs the backup.',
+                id='offsite_backup.E003',
+            )
+            for binary in self.BINARIES
+            if shutil.which(binary) is None
+        ]
+
+    def deploy_check(self) -> list[checks.CheckMessage]:
+        """Checks that touch the network or a database; run with ``check --deploy`` only."""
+        return []

offsite_backup/check.py

@@ -0,0 +1,65 @@
+"""The morning check: notice the night that never ran.
+
+It asks the store for the newest *whole* backup — objects of a pass without media do not
+count, so a deploy at noon cannot hide a night that never ran — under the config folder
+and under every database's folder. Older than ``STALE_HOURS`` or absent: MISSING, said
+and raised (so the scheduler's failure mail fires too). Store unreadable: UNCHECKED, as
+loud. Media written tonight does not stand in for a database that was not.
+"""
+
+from dataclasses import replace
+from datetime import datetime, timedelta, timezone
+
+from offsite_backup import conf, naming
+from offsite_backup.exceptions import BackupMissingError, BackupUncheckedError
+from offsite_backup.notify import notify
+from offsite_backup.outcome import MISSING, UNCHECKED, Outcome
+from offsite_backup.stores.base import Store
+
+__all__ = ('check_last_night', 'newest_whole')
+
+
+def newest_whole(store: Store, folder: str) -> datetime | None:
+    """When the newest whole backup under ``folder`` was written, or ``None``."""
+    found = [naming.parse(key) for key in store.current(folder)]
+    stamps = [name.when for name in found if name is not None and name.marker != naming.WITHOUT_MEDIA]
+    return max(stamps, default=None)
+
+
+def check_last_night(*, now: datetime | None = None) -> datetime | None:
+    """Raise unless every checked folder has a whole backup within ``STALE_HOURS``; answer the oldest newest.
+
+    ``None`` when backups are off on this machine.
+    """
+    from offsite_backup.pass_ import components  # noqa: PLC0415 - builds backends
+
+    settings = conf.read()
+    if not conf.enabled(settings):
+        return None
+    moment = now or datetime.now(timezone.utc)
+    base = Outcome(
+        kind=MISSING, prefix=settings.prefix, env=str(settings['ENV']), name=str(settings['NAME']), now=moment
+    )
+    try:
+        parts = components(conf.load())
+        kinds = [naming.CONFIG] if parts.config is not None else []
+        if parts.databases is not None:
+            kinds += [naming.db_kind(alias) for alias in parts.databases.targets()]
+        if not kinds:
+            kinds = [naming.media_kind(source.name) for source in parts.media]
+        newest = {kind: newest_whole(parts.store, naming.folder(settings.prefix, kind)) for kind in kinds}
+    except Exception as error:
+        text = f'{type(error).__name__}: {error}'
+        notify(replace(base, kind=UNCHECKED, error=text), settings)
+        raise BackupUncheckedError(text) from error
+    limit = timedelta(hours=settings.stale_hours)
+    stale = {kind: when for kind, when in newest.items() if when is None or moment - when > limit}
+    if stale:
+        oldest = min(stale.values(), key=lambda when: when or datetime.min.replace(tzinfo=timezone.utc))
+        notify(replace(base, kind=MISSING, newest=oldest, stale_hours=settings.stale_hours), settings)
+        named = ', '.join(
+            f'{kind}/ ({when:%Y-%m-%d %H:%M} UTC)' if when else f'{kind}/ (none)' for kind, when in stale.items()
+        )
+        msg = f'No whole backup within {settings.stale_hours:g} h under {settings.prefix}/: {named}'
+        raise BackupMissingError(msg)
+    return min((when for when in newest.values() if when is not None), default=None)

offsite_backup/checks.py

@@ -0,0 +1,145 @@
+"""System checks. Codes are stable; the Troubleshooting page explains each one.
+
+Network-touching checks (the bucket's lock configuration, the database server's version)
+are registered as deploy checks, so a plain ``manage.py`` never reaches S3 or the database.
+Nothing is checked on a machine where backups are off.
+"""
+
+import shutil
+import sys
+from collections.abc import Sequence
+from typing import Any
+
+from django.core import checks
+
+from offsite_backup import conf
+from offsite_backup.backend import Backend
+from offsite_backup.exceptions import BackendError
+from offsite_backup.registry import backend_class, missing_extra
+
+__all__ = ('backends', 'check_deploy', 'check_settings', 'register_all')
+
+_TAG = 'offsite_backup'
+
+
+def _under_test() -> bool:
+    return 'pytest' in sys.modules or sys.argv[1:2] == ['test']
+
+
+def backends(settings: conf.Settings) -> tuple[list[Backend], list[checks.CheckMessage]]:
+    """Every configured backend built, and an E002 for each that cannot be."""
+    from offsite_backup.notifiers.base import Notifier  # noqa: PLC0415 - base classes only
+
+    found: list[Backend] = []
+    errors: list[checks.CheckMessage] = []
+    blocks = conf._blocks(settings)  # noqa: SLF001 - the module's own table
+    blocks += [(conf.label('NOTIFY', index), block, Notifier) for index, block in enumerate(settings['NOTIFY'] or [])]
+    for name, block, base in blocks:
+        path = str(block.get('BACKEND') or '').strip()
+        install = missing_extra(path)
+        if install:
+            errors.append(
+                checks.Error(
+                    f"{name}['BACKEND'] is {path.rsplit('.', 1)[-1]}, but its driver is not installed.",
+                    hint=install,
+                    id='offsite_backup.E002',
+                )
+            )
+            continue
+        try:
+            cls = backend_class(path, base, label=name)
+        except BackendError as error:
+            errors.append(checks.Error(str(error), id='offsite_backup.E002'))
+            continue
+        found.append(cls({key: value for key, value in block.items() if key != 'BACKEND'}, label=name))
+    return found, errors
+
+
+def check_settings(app_configs: Sequence[Any] | None = None, **kwargs: Any) -> list[checks.CheckMessage]:
+    """E001-E003, E007, E008, W001-W005: everything that needs no network."""
+    settings = conf.read()
+    if not conf.enabled(settings):
+        return []
+    messages: list[checks.CheckMessage] = []
+    missing = conf.problems(settings)
+    if missing:
+        messages.append(
+            checks.Error(
+                'Backups are configured by halves; these are unset: ' + ', '.join(missing),
+                hint='Set every one, or leave the store credentials empty to turn backups off on this machine.',
+                id='offsite_backup.E001',
+            )
+        )
+    built, errors = backends(settings)
+    messages += errors
+    for backend in built:
+        messages += backend.check()
+    # the decompressor only matters where something is compressed
+    compressors = (settings['COMPRESS'], settings['DECOMPRESS']) if settings['COMPRESS'] else ()
+    for binary in sorted({command[0] for command in compressors if command}):
+        if not shutil.which(binary):
+            messages.append(
+                checks.Error(
+                    f'`{binary}` is not on PATH, and COMPRESS or DECOMPRESS runs it.',
+                    hint=f'Install {binary} in the image that runs the backup.',
+                    id='offsite_backup.E003',
+                )
+            )
+    guard = settings['GUARD']
+    if guard.get('ENABLED', True):
+        messages += _guard_cache(str(guard.get('CACHE', 'default')))
+    if _under_test() and settings['NOTIFY']:
+        from offsite_backup.notify import silenced  # noqa: PLC0415
+
+        if not silenced():
+            messages.append(
+                checks.Warning(
+                    'Notifiers are configured in a test run and not silenced.',
+                    hint='Use offsite_backup.testing.OffsiteBackupTestRunner (pytest is covered by the plugin), '
+                    "and keep production notifier tokens out of the CI test job's variables.",
+                    id='offsite_backup.W004',
+                )
+            )
+    return messages
+
+
+def _guard_cache(alias: str) -> list[checks.CheckMessage]:
+    from django.conf import settings  # noqa: PLC0415
+
+    backend = str(settings.CACHES.get(alias, {}).get('BACKEND', ''))
+    if alias not in settings.CACHES:
+        return [
+            checks.Error(
+                f"GUARD['CACHE'] is {alias!r}, which CACHES does not define.",
+                id='offsite_backup.E001',
+            )
+        ]
+    if backend.endswith(('LocMemCache', 'DummyCache')):
+        return [
+            checks.Warning(
+                f'The once-per-night guard uses cache {alias!r} ({backend.rsplit(".", 1)[-1]}), '
+                'which workers do not share.',
+                hint='Point GUARD["CACHE"] at a shared cache (Redis, Memcached, database), '
+                'or two schedulers can both run tonight.',
+                id='offsite_backup.W003',
+            )
+        ]
+    return []
+
+
+def check_deploy(app_configs: Sequence[Any] | None = None, **kwargs: Any) -> list[checks.CheckMessage]:
+    """E004-E006: the bucket's lock configuration and ``pg_dump`` against the server."""
+    settings = conf.read()
+    if not conf.enabled(settings) or conf.problems(settings):
+        return []
+    built, _ = backends(settings)
+    messages: list[checks.CheckMessage] = []
+    for backend in built:
+        messages += backend.deploy_check()
+    return messages
+
+
+def register_all() -> None:
+    """Register both checks (idempotent: Django's registry is a set)."""
+    checks.register(check_settings, _TAG)
+    checks.register(check_deploy, _TAG, deploy=True)