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 ^^^^^^^^^^^^^^^^^^^^