django-offsite-backup 0.1.0__tar.gz

django_offsite_backup-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+.idea/
+.vscode/
+venv/
+.venv/
+*.egg-info/
+
+# Python cache.
+*.py[cod]
+__pycache__/
+
+# build
+build/
+dist/
+# the documentation site, built from docs/wiki/ by `mkdocs build`
+site/
+
+# tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# JetBrains AI plugin checkpoints: 45 MB of local cache, not source
+.proxyai/
+
+# macOS
+.DS_Store

django_offsite_backup-0.1.0/AGENTS.md

@@ -0,0 +1,76 @@
+# AGENTS.md
+
+Instructions for coding agents working on **this repository**. For wiring the package into a
+project, see the wiki page [AI assistants](https://corneizer.github.io/django-offsite-backup/latest/AI-assistants/).
+
+## What this is
+
+A Django app that backs up databases, media and deployment configuration off the machine:
+compress, then encrypt to public keys, upload to a store that locks every object, rotate by
+whole nights, and say the outcome. Every backend is a dotted path in `OFFSITE_BACKUP` and is
+imported only when named.
+
+```text
+src/offsite_backup/
+    __init__.py     lazy exports (PEP 562), __version__
+    apps.py         registers the checks, imports nothing else
+    conf.py         the setting: defaults, on/off/partly-configured
+    registry.py     SHIPPED (path -> driver, extra), build()
+    backend.py      what every backend shares (REQUIRED, SIGNALS, BINARIES, checks)
+    checks.py       system checks; network ones are deploy checks
+    naming.py       object names; the night is read from the name
+    pipeline.py     subprocess pipelines with pipefail semantics, no shell
+    sealing.py      compress THEN encrypt
+    pass_.py        one pass, back_up_database, keep_apart
+    rotation.py     whole-night rotation and depth
+    guard.py        once per UTC night
+    check.py        the morning check
+    restore.py      download, decrypt, verify, load
+    notify.py       formatter + notifiers; silence() and capture()
+    outcome.py      the records messages are written from
+    messages/       the shipped format
+    notifiers/ databases/ media/ config/ encryption/ stores/   one backend per module
+    schedule/       Celery and taskiq adapters, imported only by projects using them
+    management/commands/   backup_offsite, backup_check, backup_list, backup_restore
+    testing/        FakeS3, Passthrough, use_fake_s3, the runner and the pytest plugin
+```
+
+## Commands
+
+```shell
+uv venv && uv pip install -e '.[all]' --group dev
+ruff check . && ruff format --check . && mypy && python -m pytest -q
+```
+
+Integration (real PostgreSQL, an S3 server with Object Lock, `age`, `zstd`) — see
+`CONTRIBUTING.md`:
+
+```shell
+OFFSITE_BACKUP_TEST_S3_ENDPOINT=http://127.0.0.1:9000 OFFSITE_BACKUP_TEST_PG_PORT=5432 \
+  python -m pytest -m integration --ds=tests.integration_settings tests/integration
+```
+
+## Rules
+
+- **Nothing happens at import time.** `import offsite_backup` loads no driver; every backend
+  imports its driver inside the function that needs it. `tests/test_checks_commands.py`
+  imports every module with every driver blocked.
+- **No private references.** This package is public: no company, client, product, host or
+  ticket names in code, docs, tests or commit messages. Examples use `acme/prod`.
+- **Every change carries a test that fails without it.** Swap the source, watch it go red,
+  put it back — never `git checkout` a file with uncommitted work. One case per guard; no
+  case that fails for an earlier reason.
+- **A notifier never raises and never costs the backup**; it logs the error class, never the
+  text it sends or a token.
+- **Secrets travel in the environment, never in argv**: argv is visible in `ps`, and error
+  text is posted to a chat.
+- **The lock is an argument of every upload and is read back.** Do not rely on a bucket
+  default for a single PUT.
+- **Rotation is scoped to `<prefix>/<kind>/` with the trailing slash**, counts nights read
+  from names, deletes versions (never a bare key), and leaves locked versions for later.
+- A settings rename or a default flip is a major version.
+
+## Style
+
+Code, comments, docstrings and docs in English. A comment is one line for the non-obvious
+*why*; module docstrings explain design. Commits and pull requests carry no AI attribution.

django_offsite_backup-0.1.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project are documented here. The project follows
+[semantic versioning](https://semver.org/): renaming a setting or flipping a default is a
+major version.
+
+## 0.1.0 — 2026-11-03
+
+First release.
+
+- A pass: PostgreSQL databases (a list, or computed at run time; plain or custom format),
+  media in volumes of whole files (a directory, a Docker volume mounted as one, or an S3
+  bucket), and the deployment configuration with the environment rebuilt from a list of
+  names — compressed with zstd, encrypted with age to one or more recipients.
+- Stores: S3 with Object Lock COMPLIANCE passed on every upload and read back, versions and
+  delete markers, pagination; a local directory (no immutability, W001).
+- Whole-night rotation per kind; passes without media (`--without-media`) never count as a
+  night; depth reported after rotation.
+- One database failing does not cost the others their night; the pass fails at the end
+  naming each one.
+- Once-per-night guard for the nightly pass; the morning check (MISSING / UNCHECKED).
+- Messages in one HTML format; notifiers: log, Telegram (`[telegram]`), django-aiogram
+  (`[aiogram]`). Notifiers are silenced for every test run.
+- `back_up_database` (extra recipients, `keep_apart`), `keep_apart`, `restore_database`.
+- Commands: `backup_offsite`, `backup_check`, `backup_list`, `backup_restore` (download,
+  decrypt, verify; `--apply` loads a database).
+- System checks E001–E008, W001–W005.
+- Celery and taskiq adapters.
+- `offsite_backup.testing`: FakeS3, Passthrough, `use_fake_s3`, `capture`, the test runner
+  and the pytest plugin.

django_offsite_backup-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing
+
+## Set up
+
+```shell
+uv venv
+uv pip install -e '.[all]' --group dev      # pip 25.1+ also understands --group
+```
+
+## The gate
+
+```shell
+ruff check . && ruff format --check . && mypy && python -m pytest -q
+```
+
+The unit suite needs no network and no binary beyond a POSIX shell: it runs against an
+in-memory S3 (`offsite_backup.testing.FakeS3`) and a pass-through sealer.
+
+## Integration
+
+A full cycle against real services — backup, restore into a clean database, row counts of
+every table compared; media volumes byte for byte; Object Lock read back; rotation over real
+versions and delete markers.
+
+```shell
+docker run -d --rm --name ob-pg -e POSTGRES_USER=ob -e POSTGRES_PASSWORD=ob -e POSTGRES_DB=source \
+  -p 5432:5432 postgres:17
+docker exec ob-pg psql -U ob -d source -c 'CREATE DATABASE target'
+docker run -d --rm --name ob-s3 -e MINIO_ROOT_USER=minio -e MINIO_ROOT_PASSWORD=minio12345 \
+  -p 9000:9000 cgr.dev/chainguard/minio:latest server /data
+
+OFFSITE_BACKUP_TEST_S3_ENDPOINT=http://127.0.0.1:9000 \
+  python -m pytest -m integration --ds=tests.integration_settings tests/integration
+```
+
+It needs `age`, `age-keygen`, `zstd`, `pg_dump`, `psql` and `pg_restore` on PATH, the client
+at least as new as the server. Variables: `OFFSITE_BACKUP_TEST_PG_{HOST,PORT,USER,PASSWORD,SOURCE,TARGET}`,
+`OFFSITE_BACKUP_TEST_S3_{ENDPOINT,ACCESS_KEY,SECRET_KEY}`. Each run creates fresh buckets:
+COMPLIANCE locks cannot be lifted, so do not point it at a store you care about.
+
+## Pull requests
+
+One change per pull request, with a test that fails without it, and the wiki page that
+describes the behaviour updated in the same pull request (`docs/wiki/`, built with
+`mkdocs build --strict`). Add a line to `CHANGELOG.md`.
+
+## Releasing
+
+Bump `__version__` in `src/offsite_backup/__init__.py`, move the changelog section out of
+"Unreleased", merge, then tag `vX.Y.Z` on master and push the tag. `publish.yml` checks the tag
+against `__version__`, builds, smoke-installs the wheel, publishes to PyPI by trusted
+publishing and creates the GitHub release.

django_offsite_backup-0.1.0/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.

django_offsite_backup-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,88 @@
+# 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/SECURITY.md

@@ -0,0 +1,22 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Please report security issues privately through GitHub's
+[private vulnerability reporting](https://github.com/CorneiZeR/django-offsite-backup/security/advisories/new),
+not in a public issue. Expect an acknowledgement within a few days.
+
+## Supported versions
+
+The latest minor release receives security fixes.
+
+## What the package promises
+
+- The server holds **public** keys only; a backup it wrote cannot be read with anything on it.
+- Every object in an S3 store is written with Object Lock COMPLIANCE and the lock is read back;
+  the key the server holds cannot delete a locked object.
+- Credentials reach subprocesses through the environment, never the command line, and no
+  notifier logs a token or the message body.
+
+The [Security model](https://corneizer.github.io/django-offsite-backup/latest/Security-model/)
+page describes the threat model and its limits.

django_offsite_backup-0.1.0/docs/wiki/AI-assistants.md

@@ -0,0 +1,105 @@
+# AI assistants
+
+Coding agents wire this package into a project the way a person would — by reading the
+docs — and the mistakes they make are the expensive kind: a private key on the server, a
+test suite posting to the team's chat, a bucket without Object Lock. This page is the
+brief to hand them.
+
+## Paste this in
+
+Short enough for a system prompt or a `CLAUDE.md` / `AGENTS.md` / `.cursor/rules` file:
+
+```text
+Project uses django-offsite-backup 0.1. Rules:
+
+- Install with the extras the configuration names, nothing inferred:
+  `django-offsite-backup[s3,telegram]` for an S3 store and Telegram messages,
+  `[s3,aiogram]` to send through the project's django-aiogram bot. Add
+  'offsite_backup' to INSTALLED_APPS. It has no models and no migrations.
+- The image that runs a pass needs the binaries: pg_dump (major >= the
+  PostgreSQL server's), zstd, age. Not tar. Install them in the worker's image
+  AND the image the deploy pass runs in.
+- Settings are one dict, OFFSITE_BACKUP, in settings.py. Read EVERY credential
+  from the environment with a default of '' — os.environ.get('X', '') — never
+  os.environ['X'] and never a placeholder value. Empty means "backups off on this
+  machine", which is what developer laptops and CI want.
+- The age RECIPIENTS is a public key and may be read from the environment or
+  written into settings; it does not switch backups on by itself.
+- Backend paths, exactly:
+  offsite_backup.stores.s3.S3Store / offsite_backup.stores.filesystem.DirectoryStore
+  offsite_backup.encryption.age_cli.AgeCli
+  offsite_backup.databases.postgres.PostgresSource
+  offsite_backup.media.filesystem.DirectorySource / offsite_backup.media.s3.S3Source
+  offsite_backup.config.paths.PathsSource
+  offsite_backup.notifiers.telegram.TelegramNotifier
+  offsite_backup.notifiers.django_aiogram.TopicNotifier
+  offsite_backup.notifiers.log.LogNotifier
+- NEVER put an age private key (AGE-SECRET-KEY-...) on the server, in settings,
+  in .env, in CI variables, or in the repository. RECIPIENTS takes public keys
+  (age1...). The private key is generated on a person's machine with age-keygen
+  and kept in their password manager. E008 refuses a private key in RECIPIENTS.
+  Do not generate a key pair for the user: tell them to run age-keygen and give
+  you the public half.
+- The S3 bucket must be created WITH Object Lock (it cannot be enabled later)
+  and given a default retention rule COMPLIANCE, days == STORE['LOCK_DAYS']
+  (13). Keep RETENTION['KEEP_NIGHTS'] (14) greater than LOCK_DAYS. Never
+  suggest GOVERNANCE mode. Never "fix" E005/E006 by setting LOCK_DAYS to 0
+  without the user explicitly accepting backups that the server can delete.
+- PREFIX is required ('<project>/<env>', e.g. 'acme/prod'). Rotation never
+  leaves it.
+- Scheduling: Celery -> CELERY_BEAT_SCHEDULE = {**beat_schedule(), ...} from
+  offsite_backup.schedule.celery, with CELERY_IMPORTS including
+  'offsite_backup.schedule.celery' and the beat in UTC. taskiq ->
+  register(broker) from offsite_backup.schedule.taskiq. cron -> 03:00 UTC
+  `manage.py backup_offsite --reason nightly`, 09:00 UTC `manage.py backup_check`.
+  The guard needs GUARD['CACHE'] to be a cache shared by every worker (Redis,
+  Memcached, database) — not LocMemCache (W003).
+- Deploy: run `python manage.py backup_offsite --without-media --reason deploy`
+  on the NEW image BEFORE `migrate`, and let a non-zero exit stop the deploy.
+  Do not add `|| true`. Mount the deployment directory read-only into the service
+  that runs it AND into the worker.
+- Validate with `python manage.py check` and `python manage.py check --deploy`.
+  Treat offsite_backup.E0xx/W0xx as the spec. Do not silence an error; only
+  W001 (directory store) may be silenced, and only where the user chose it.
+- Tests must never notify. pytest is covered by the package's plugin
+  automatically; with Django's runner set
+  TEST_RUNNER = 'offsite_backup.testing.OffsiteBackupTestRunner' (or mix it in).
+  Do not give CI test jobs the production notifier token or store keys. In
+  tests use offsite_backup.testing: use_fake_s3(FakeS3()), Passthrough as the
+  ENCRYPTION backend with COMPRESS [], capture() to assert on messages,
+  media_tree() for media. Passthrough is for tests only (W002).
+- Restore: `manage.py backup_restore --stamp latest --into DIR` with the
+  private key in AGE_IDENTITY or --identity FILE, run by a person on their own
+  machine. Never write code that stores the identity on the server.
+```
+
+## Prompts that work
+
+**Wire it in.** *"Add django-offsite-backup to this project: S3 store with credentials
+from `BACKUP_S3_*` variables, age recipient from `BACKUP_AGE_RECIPIENT`, PostgreSQL
+`default`, media from `MEDIA_ROOT`, the `deploy/` directory as configuration, Telegram from
+`BACKUP_TELEGRAM_*`. Add the Celery beat entries, the pre-migration step to our deploy script,
+the read-only mount on web and worker, the binaries to the Dockerfile, and
+`OffsiteBackupTestRunner`. Do not generate keys. Show me `manage.py check` output with the
+variables unset."* — the last sentence is the test that the laptop stays "off".
+
+**Review a wiring.** *"Check our OFFSITE_BACKUP settings and deploy script against the
+django-offsite-backup docs: credentials from the environment with '' defaults, no private
+key anywhere, backup before migrate with a failing exit stopping the deploy, mounts on
+both services, notifier silenced in tests."*
+
+**Prepare a bucket.** *"Give me the AWS CLI commands to create a bucket with Object Lock and
+a default COMPLIANCE rule of 13 days on <provider>, and a least-privilege policy for the
+backup key under prefix `acme/prod/`. Do not run them."*
+
+## What to check after an agent is done
+
+* `grep -rn "AGE-SECRET-KEY" .` finds nothing — in the repository, the CI configuration or
+  the server's `.env`.
+* `python manage.py check` with the backup variables **unset** reports no `offsite_backup`
+  code (the machine is off); with them set, none but warnings you chose.
+* `python manage.py check --deploy` on the server: no `E004`, `E005`, `E006`.
+* The deploy script stops when `backup_offsite` exits non-zero — try it once with a wrong
+  bucket name on staging.
+* The test job's environment holds no production notifier token.
+* Someone has restored a backup — [Restore](Restore.md).

django_offsite_backup-0.1.0/docs/wiki/Changelog.md

@@ -0,0 +1,58 @@
+# Changelog
+
+## 0.1.0 — unreleased
+
+The first release.
+
+**A pass.** `manage.py backup_offsite` (and `offsite_backup.run()`) backs up the
+databases, the media and the deployment configuration, one part at a time, then rotates.
+A database that fails does not cost the others their night; the pass fails at the end
+naming every one. `--without-media` and `--only` for partial passes; `--reason` for the
+message.
+
+**Databases.** `offsite_backup.databases.postgres.PostgresSource`: one alias, a list, or a
+callable that computes them at run time; plain SQL (`.sql.zst.age`) or the custom format
+(`.dump.zst.age`, `pg_dump`'s compression off, then zstd). The password travels in
+`PGPASSWORD`, never on a command line. `back_up_database()` for a one-off dump with extra
+recipients, and `keep_apart` to set one aside from rotation.
+
+**Media.** `offsite_backup.media.filesystem.DirectorySource` and
+`offsite_backup.media.s3.S3Source`: volumes of whole files (4 GiB by default), each a
+complete tar written with Python's `tarfile`, streamed one at a time; `INCLUDE`/`EXCLUDE`
+globs; several sources.
+
+**Configuration.** `offsite_backup.config.paths.PathsSource`: listed paths plus the
+environment rebuilt from a list of names, written last.
+
+**Encryption.** `offsite_backup.encryption.age_cli.AgeCli`: compress, then encrypt, to one
+or more public keys, under pipefail semantics.
+
+**Stores.** `offsite_backup.stores.s3.S3Store`: every upload locked COMPLIANCE by its own
+arguments and read back; multipart in 64 MiB parts; versions and delete markers handled;
+pagination everywhere; only the configured credentials.
+`offsite_backup.stores.filesystem.DirectoryStore`: atomic writes, `0600` files, and a
+warning that it has no immutability.
+
+**Retention.** Whole UTC nights read from object names, per kind; passes without media never
+count as nights; every version deleted; locked versions left for a later night; depth in
+the message.
+
+**Messages.** One HTML format for written, failed, missing and unchecked, every value
+escaped. Notifiers: `LogNotifier`, `TelegramNotifier` (`[telegram]`, httpx2),
+`TopicNotifier` through django-aiogram (`[aiogram]`). A notifier never costs the backup.
+
+**Scheduling.** `run_nightly()` with a once-per-night guard in a shared cache; Celery
+(`offsite_backup.schedule.celery.beat_schedule`) and taskiq
+(`offsite_backup.schedule.taskiq.register`) adapters.
+
+**Monitoring.** `manage.py backup_check` — the morning check over the configuration folder
+and every database's; `LAST_SUCCESS_FILE`; `manage.py backup_list`.
+
+**Restore.** `manage.py backup_restore`: download, decrypt and verify every object of a
+stamp; `--apply` loads a database (`--from-database`, `--clean`); `restore_database()`.
+
+**System checks.** `E001`–`E008`, `W001`–`W005`; network checks under `check --deploy`
+only.
+
+**Testing.** A pytest plugin and `OffsiteBackupTestRunner` that silence network
+notifiers; `capture()`, `FakeS3`, `use_fake_s3`, `Passthrough`, `media_tree`.