From 5f3c691c383c45993615247100b4130875bb3c2e Mon Sep 17 00:00:00 2001 From: Sunil Mohan Adapa Date: Sun, 27 Sep 2020 20:43:43 -0700 Subject: [PATCH] doc: dev: Update documentation for using backup component Signed-off-by: Sunil Mohan Adapa Reviewed-by: Veiko Aasa --- doc/dev/reference/components/backups.rst | 7 ++++ doc/dev/reference/components/index.rst | 1 + doc/dev/tutorial/components.rst | 46 ++++++++++++++++++++++++ doc/dev/tutorial/other.rst | 31 ---------------- 4 files changed, 54 insertions(+), 31 deletions(-) create mode 100644 doc/dev/reference/components/backups.rst diff --git a/doc/dev/reference/components/backups.rst b/doc/dev/reference/components/backups.rst new file mode 100644 index 000000000..0afed3842 --- /dev/null +++ b/doc/dev/reference/components/backups.rst @@ -0,0 +1,7 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +Backups +^^^^^^^ + +.. autoclass:: plinth.modules.backups.components.BackupRestore + :members: diff --git a/doc/dev/reference/components/index.rst b/doc/dev/reference/components/index.rst index 3d0d33de5..a32ef3e7e 100644 --- a/doc/dev/reference/components/index.rst +++ b/doc/dev/reference/components/index.rst @@ -15,6 +15,7 @@ Components domain letsencrypt staticfiles + backups Base Classes ^^^^^^^^^^^^ diff --git a/doc/dev/tutorial/components.rst b/doc/dev/tutorial/components.rst index 5886fcf23..7321d77aa 100644 --- a/doc/dev/tutorial/components.rst +++ b/doc/dev/tutorial/components.rst @@ -229,3 +229,49 @@ a later section of this tutorial. The next parameter specifies whether anonymous users who are not logged into FreedomBox should be shown this shortcut. The final parameter further restricts to which group of users this shortcut must be shown. + +Adding backup/restore functionality +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Each app in FreedomBox needs to provide the ability to backup and restore its +configuration and data. Apart from providing durability to users' data, this +allows the user to migrate from one machine to another. FreedomBox framework +provides a component for handling these operations. Create the +:class:`~plinth.modules.backups.components.BackupRestore` component during app +initialization. + +In ``__init__.py``, add: + +.. code-block:: python3 + + from plinth.modules.backups.components import BackupRestore + + from . import manifest + + class TransmissionApp(app_module.App): + ... + + def __init__(self): + ... + + backup_restore = BackupRestore('backup-restore-transmission', + **manifest.backup) + self.add(backup_restore) + +In ``manifest.py``, add: + +.. code-block:: python3 + + backup = { + 'data': { + 'directories': ['/var/lib/transmission-daemon/.config'] + }, + 'secrets': { + 'files': ['/etc/transmission-daemon/settings.json'] + }, + 'services': ['transmission-daemon'] + } + +The data and secrets information specifies which list of files and directories +FreedomBox framework needs to backup and restore. The list of services specifies +which daemons should be stopped during the backup and restore process. diff --git a/doc/dev/tutorial/other.rst b/doc/dev/tutorial/other.rst index da42cd9d2..cf233a938 100644 --- a/doc/dev/tutorial/other.rst +++ b/doc/dev/tutorial/other.rst @@ -68,37 +68,6 @@ Then, in ``views.py``, add: ... manual_page = transmission.manual_page -Adding backup/restore functionality -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Each app in FreedomBox needs to provide the ability to backup its configuration -and data. Apart from providing durability to users' data, this allows the user -to migrate from one machine to another. FreedomBox framework provides a simple -declarative mechanism to allow the app to be backed up and restored. In -``manifest.py``, add: - -.. code-block:: python3 - - from plinth.modules.backups.api import validate as validate_backup - - backup = validate_backup({ - 'data': { - 'directories': ['/var/lib/transmission-daemon/.config'] - }, - 'secrets': { - 'files': ['/etc/transmission-daemon/settings.json'] - }, - 'services': ['transmission-daemon'] - }) - -The data and secrets information specifies which list of files and directories -FreedomBox framework needs to backup. The list of services specifies which -daemons should be stopped during the backup process. In ``__init__.py``, add: - -.. code-block:: python3 - - from .manifest import backup - Creating diagnostics ^^^^^^^^^^^^^^^^^^^^