django-backupgram 0.1.0__tar.gz

django_backupgram-0.1.0/.github/workflows/ci-cd.yml

@@ -0,0 +1,65 @@
+name: CI/CD
+
+on:
+  push:
+    branches: [main]
+    tags:
+      - "v*"
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+        django-version: ["5.2", "6.0"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Setup Python
+        env:
+          PYTHON_VERSION: "${{ matrix.python-version }}"
+        run: uv python install "$PYTHON_VERSION"
+
+      - name: Install dependencies
+        env:
+          DJANGO_VERSION: "${{ matrix.django-version }}"
+        run: |
+          uv sync --group dev
+          uv pip install "Django~=${DJANGO_VERSION}.0"
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Test
+        run: uv run pytest --cov
+
+  publish:
+    name: Publish to PyPI
+    needs: test
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Build
+        run: uv build
+
+      - name: Publish
+        run: uv publish --trusted-publishing always

django_backupgram-0.1.0/.gitignore

@@ -0,0 +1,143 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+media/
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# uv specific
+.uv/
+__pypackages__/
+
+# Poetry specific
+poetry.lock
+
+# macOS
+.DS_Store
+
+# Windows
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+# Coverage.py
+.coverage.*
+coverage.xml
+htmlcov/
+
+# Example project runtime
+example/db.sqlite3

django_backupgram-0.1.0/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-07
+
+Initial release — a Django admin control panel for the `backupgram`
+(postgres-backup) REST API. It is a thin, well-tested client: it performs no
+backups itself, it drives one or more backup containers over their REST API.
+
+### Added
+
+- **`BackupServer` model** — register one or more backup servers (`base_url`,
+  bearer `token`, `verify_tls`, `timeout`, `enabled`). The token is **encrypted
+  at rest** with Fernet (key derived from `SECRET_KEY`) and is **write-only** in
+  admin (never rendered). `base_url` accepts single-label hosts, e.g.
+  `https://backup:8081` (Docker service names).
+- **`BackupgramClient`** — typed `httpx` wrapper over every REST endpoint
+  (status, list/download/delete backups, trigger backup, restore from a stored
+  file or a Telegram message id, jobs, runtime config) with a `BackupgramAPIError`
+  that carries the HTTP status and parses the API's `{"error": ...}` envelope.
+- **Admin dashboard** — server overview with a live connection indicator, KPI
+  cards (schedule with a human-readable cron description, last backup, next
+  backup), a status & configuration card grid (upload mode, Telegram / MTProto
+  state, cluster, previous backup), misconfiguration **warnings** (e.g. upload
+  method `mtproto` without API credentials), and a recent-backups panel.
+- **Backups page** — list, stream-download, and delete (with confirmation),
+  human-readable sizes and relative times.
+- **Jobs** — recent-jobs list and a live job-detail view that auto-refreshes
+  while a job is running.
+- **Restore page** — restore from a stored file or a Telegram message id;
+  clicking an available backup fills the file field. Server-side `target_db`
+  validation and explicit confirmation are required.
+- **Runtime config** — settings grouped into sections (Schedule / Retention /
+  Databases / Telegram / Webhook), each rendered with the right widget: enum
+  **selects** with per-value help (including `TELEGRAM_UPLOAD_METHOD`), numbers,
+  write-only secrets, and a **live cron editor** (bundled cronstrue, MIT) with
+  preset shortcuts. Only whitelisted keys are editable; secrets are masked.
+- **Next-run calculation** — computed in pure standard library (no external
+  cron dependency), supporting 5-field cron and `@shortcut` schedules.
+- **Theming** — a data-dense dashboard UI that follows Django admin's light/dark
+  theme; CSS and JS are bundled and shipped in the wheel.
+- **Packaging** — `src/` layout, Python 3.11–3.13 / Django 5.2+, PyPI
+  trusted-publishing release workflow, and an `example/` project for local
+  testing against a running backup container.
+
+### Security
+
+- Server tokens are encrypted at rest and never returned to the browser; all
+  REST calls happen server-side. Admin views are permission-gated, destructive
+  actions are POST + CSRF + explicit confirm, and config secrets are masked
+  (write-only). **Note:** rotating `SECRET_KEY` invalidates stored tokens.
+
+[Unreleased]: https://github.com/ganiyevuz/django-backupgram/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/ganiyevuz/django-backupgram/releases/tag/v0.1.0

django_backupgram-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jakhongir Ganiev
+
+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_backupgram-0.1.0/Makefile

@@ -0,0 +1,41 @@
+.PHONY: help venv install lint format test coverage dist publish release example clean
+
+help: ## Show available commands
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  %-12s %s\n", $$1, $$2}'
+
+venv: ## Create virtual environment
+	uv venv
+
+install: ## Install with dev dependencies
+	uv sync --group dev
+
+lint: ## Check code style
+	uv run ruff check .
+	uv run ruff format --check .
+
+format: ## Format code
+	uv run ruff check --fix .
+	uv run ruff format .
+
+test: ## Run tests
+	uv run pytest
+
+coverage: ## Run tests with coverage
+	uv run pytest --cov
+
+dist: clean ## Build package
+	uv build
+
+publish: dist ## Publish to PyPI
+	uv publish
+
+example: ## Create example Django project
+	@./scripts/create_example_project.sh
+
+release: lint test ## Release a version (usage: make release v=0.2.0)
+	@./scripts/release.sh $(v)
+
+clean: ## Remove build artifacts
+	rm -rf build/ dist/ *.egg-info
+	find . -type d -name __pycache__ -exec rm -rf {} +
+	find . -type f -name '*.py[co]' -delete

django_backupgram-0.1.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: django-backupgram
+Version: 0.1.0
+Summary: Django admin control panel for the backupgram REST API (PostgreSQL backups over HTTP).
+Project-URL: Homepage, https://github.com/ganiyevuz/django-backupgram
+Project-URL: Repository, https://github.com/ganiyevuz/django-backupgram
+Author-email: Jakhongir Ganiev <contact@jakhongir.dev>
+License: MIT
+License-File: LICENSE
+Keywords: admin,backup,backupgram,django,postgres
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=42
+Requires-Dist: django-jazzmin>=3.0.4
+Requires-Dist: django>=5.2
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# django-backupgram
+
+A Django admin control panel for the [backupgram REST API](https://github.com/ganiyevuz/backupgram).
+
+## What it is
+
+`django-backupgram` is a thin Django admin client. It talks to one or more
+[backupgram](https://github.com/ganiyevuz/backupgram)
+containers over their REST API, letting you:
+
+- **Trigger backups** on demand
+- **Browse and download** backup files
+- **Delete** old backups
+- **Restore** a backup to a target database
+- **Watch async jobs** (restore, backup) as they run
+- **Edit runtime config** of the backup container
+
+It does **not** perform backups itself — the backup logic lives entirely inside
+the containers. `django-backupgram` is only the admin UI that drives them.
+
+## Requirements
+
+- Python 3.11 – 3.13
+- Django 5.2+
+- One or more backup containers reachable from the Django server with
+  `REST_API_ENABLE=TRUE` and a `REST_API_TOKEN` set
+
+See the backup container's
+[REST API docs](https://github.com/ganiyevuz/backupgram/blob/main/docs/REST_API.md)
+for how to enable the API.
+
+## Install
+
+```bash
+pip install django-backupgram
+```
+
+## Setup
+
+1. Add `"backupgram"` to `INSTALLED_APPS`:
+
+   ```python
+   INSTALLED_APPS = [
+       ...
+       "backupgram",
+   ]
+   ```
+
+2. Run migrations:
+
+   ```bash
+   python manage.py migrate
+   ```
+
+3. Open Django admin → **Backup servers** → **Add**, and fill in:
+   - **Name** — a friendly label (e.g. `production`)
+   - **Base URL** — the backup container's REST API endpoint, e.g.
+     `https://backup:8081`. Docker service names are allowed (the request is
+     made server-side).
+   - **Token** — the bearer token configured via `REST_API_TOKEN` on the container
+     (see below).
+
+### The API token
+
+The token is the backup container's single admin bearer key — you generate it
+yourself and set it on the container, then paste the **same** value into the
+**Token** field here.
+
+Generate a high-entropy value (≥ 32 bytes of randomness):
+
+```bash
+openssl rand -base64 48
+# or
+python3 -c "import secrets; print(secrets.token_urlsafe(48))"
+```
+
+Set it on the backup container via `REST_API_TOKEN` (or, recommended,
+`REST_API_TOKEN_FILE` pointing at a Docker secret), then enter the same token in
+admin. The container compares it in constant time and refuses to start if the API
+is enabled without one; here it is stored **encrypted at rest** and sent only
+server-side. To **rotate**: change it on the container, recreate it, and update
+the Token field. See the
+[REST API auth docs](https://github.com/ganiyevuz/backupgram/blob/main/docs/REST_API.md#authentication).
+
+## Usage
+
+From the **Backup servers** changelist, each server row shows a reachability
+badge and links to its dashboard. The dashboard provides:
+
+| Action | Notes |
+|--------|-------|
+| **Run backup** | Triggers an immediate backup |
+| **Backups** | Lists all backup files; download or delete individual files |
+| **Restore** | Select a file, enter the target database name, confirm |
+| **Jobs** | Live view of async jobs (backup/restore in progress) |
+| **Config** | View and edit the container's runtime configuration |
+
+Long-running operations (restore, triggered backup) run as async jobs inside
+the backup container. Refresh the Jobs page to see progress and final status.
+
+## Security
+
+- The bearer token is stored **encrypted at rest** using Fernet symmetric
+  encryption. The key is derived from Django's `SECRET_KEY`.
+- The token is **write-only** in the admin interface — it is never rendered back
+  into any form or page.
+- **Rotating `SECRET_KEY` invalidates all stored tokens.** After a key rotation,
+  re-enter each server's token in the admin.
+- All REST calls are made **server-side** — the token never reaches the browser.
+- Put the backup container's REST API behind **TLS and a reverse proxy**. Do not
+  expose it directly on a public network.
+
+## Optional settings
+
+Add to your Django settings to override defaults:
+
+```python
+# Timeout (seconds) for the reachability check shown in the changelist badge.
+# Default: 3
+BACKUPGRAM_REACHABILITY_TIMEOUT = 3
+```
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+```
+
+## Links
+
+- Backup container: <https://github.com/ganiyevuz/backupgram>
+- REST API reference: <https://github.com/ganiyevuz/backupgram/blob/main/docs/REST_API.md>
+- This package: <https://github.com/ganiyevuz/django-backupgram>

django_backupgram-0.1.0/README.md

@@ -0,0 +1,134 @@
+# django-backupgram
+
+A Django admin control panel for the [backupgram REST API](https://github.com/ganiyevuz/backupgram).
+
+## What it is
+
+`django-backupgram` is a thin Django admin client. It talks to one or more
+[backupgram](https://github.com/ganiyevuz/backupgram)
+containers over their REST API, letting you:
+
+- **Trigger backups** on demand
+- **Browse and download** backup files
+- **Delete** old backups
+- **Restore** a backup to a target database
+- **Watch async jobs** (restore, backup) as they run
+- **Edit runtime config** of the backup container
+
+It does **not** perform backups itself — the backup logic lives entirely inside
+the containers. `django-backupgram` is only the admin UI that drives them.
+
+## Requirements
+
+- Python 3.11 – 3.13
+- Django 5.2+
+- One or more backup containers reachable from the Django server with
+  `REST_API_ENABLE=TRUE` and a `REST_API_TOKEN` set
+
+See the backup container's
+[REST API docs](https://github.com/ganiyevuz/backupgram/blob/main/docs/REST_API.md)
+for how to enable the API.
+
+## Install
+
+```bash
+pip install django-backupgram
+```
+
+## Setup
+
+1. Add `"backupgram"` to `INSTALLED_APPS`:
+
+   ```python
+   INSTALLED_APPS = [
+       ...
+       "backupgram",
+   ]
+   ```
+
+2. Run migrations:
+
+   ```bash
+   python manage.py migrate
+   ```
+
+3. Open Django admin → **Backup servers** → **Add**, and fill in:
+   - **Name** — a friendly label (e.g. `production`)
+   - **Base URL** — the backup container's REST API endpoint, e.g.
+     `https://backup:8081`. Docker service names are allowed (the request is
+     made server-side).
+   - **Token** — the bearer token configured via `REST_API_TOKEN` on the container
+     (see below).
+
+### The API token
+
+The token is the backup container's single admin bearer key — you generate it
+yourself and set it on the container, then paste the **same** value into the
+**Token** field here.
+
+Generate a high-entropy value (≥ 32 bytes of randomness):
+
+```bash
+openssl rand -base64 48
+# or
+python3 -c "import secrets; print(secrets.token_urlsafe(48))"
+```
+
+Set it on the backup container via `REST_API_TOKEN` (or, recommended,
+`REST_API_TOKEN_FILE` pointing at a Docker secret), then enter the same token in
+admin. The container compares it in constant time and refuses to start if the API
+is enabled without one; here it is stored **encrypted at rest** and sent only
+server-side. To **rotate**: change it on the container, recreate it, and update
+the Token field. See the
+[REST API auth docs](https://github.com/ganiyevuz/backupgram/blob/main/docs/REST_API.md#authentication).
+
+## Usage
+
+From the **Backup servers** changelist, each server row shows a reachability
+badge and links to its dashboard. The dashboard provides:
+
+| Action | Notes |
+|--------|-------|
+| **Run backup** | Triggers an immediate backup |
+| **Backups** | Lists all backup files; download or delete individual files |
+| **Restore** | Select a file, enter the target database name, confirm |
+| **Jobs** | Live view of async jobs (backup/restore in progress) |
+| **Config** | View and edit the container's runtime configuration |
+
+Long-running operations (restore, triggered backup) run as async jobs inside
+the backup container. Refresh the Jobs page to see progress and final status.
+
+## Security
+
+- The bearer token is stored **encrypted at rest** using Fernet symmetric
+  encryption. The key is derived from Django's `SECRET_KEY`.
+- The token is **write-only** in the admin interface — it is never rendered back
+  into any form or page.
+- **Rotating `SECRET_KEY` invalidates all stored tokens.** After a key rotation,
+  re-enter each server's token in the admin.
+- All REST calls are made **server-side** — the token never reaches the browser.
+- Put the backup container's REST API behind **TLS and a reverse proxy**. Do not
+  expose it directly on a public network.
+
+## Optional settings
+
+Add to your Django settings to override defaults:
+
+```python
+# Timeout (seconds) for the reachability check shown in the changelist badge.
+# Default: 3
+BACKUPGRAM_REACHABILITY_TIMEOUT = 3
+```
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+```
+
+## Links
+
+- Backup container: <https://github.com/ganiyevuz/backupgram>
+- REST API reference: <https://github.com/ganiyevuz/backupgram/blob/main/docs/REST_API.md>
+- This package: <https://github.com/ganiyevuz/django-backupgram>

django_backupgram-0.1.0/example/README.md

@@ -0,0 +1,33 @@
+# Example project
+
+A minimal, local-only Django project for manually exercising `django-backupgram`
+against a running backup container. **Not** shipped in the published wheel.
+
+## Prerequisites
+
+A reachable backup container with the REST API enabled. The companion repo's
+`docker-compose.local.yml` publishes it on `127.0.0.1:8081` with token `devsecret`:
+
+```sh
+# in the backupgram repo:
+docker compose -f docker-compose.local.yml up -d
+```
+
+## Run
+
+From the `django-backupgram` repo root:
+
+```sh
+uv run python example/manage.py migrate      # create the SQLite db
+uv run python example/seed.py                # superuser admin/admin + a 'local' BackupServer
+uv run python example/manage.py runserver    # http://localhost:8000/admin/
+```
+
+Log in as `admin` / `admin`, open **Backup servers → local**, and use the
+dashboard: Run backup, browse/download/restore backups, watch jobs, edit config.
+
+Override the target via env if your container is elsewhere:
+
+```sh
+BACKUPGRAM_DEMO_URL=http://localhost:8081 BACKUPGRAM_DEMO_TOKEN=devsecret uv run python example/seed.py
+```