Rework Backup & Restore (#211)

* Add: EOL warning message to Univention related pages

* Maintenance: Break too long lines in tables

* Maintenance: Begin Rework of Backup & Restore

* Maintenance: beautify getting started of backup and restore

* Maintenance: Add non full file system backup option

* Improve: Add upgrade path notes to update page

* Improve: Add configuration details for `HOLD_DAYS`

* Fixes #185 - Maintenance: Rework Backup & Restore parts

* Maintenance: Improve restore page

* Introduce Migrate Zammad in between hosts section

* Add clear warning for old dumps and their database.yml

* Fix distribution typos

* Maintenance: Improve wording based on QA

_static/theme/theme_overrides.css

@@ -58,3 +58,11 @@
     border: inherit;
     box-sizing: inherit;
 }
+
+.wy-table-responsive table td, .wy-table-responsive table th {
+    white-space: normal;
+}
+
+.rst-content table.docutils td {
+    vertical-align: top;
+}

appendix/backup-and-restore/add-missing-environment.include.rst

@@ -0,0 +1,11 @@
+   If you've set any environmental settings like higher web concurrency
+   due to required :ref:`performance_tuning`, please re-apply your settings now.
+
+   If not already done, please install Elasticsearch now (if you want to use it).
+   Follow :ref:`configure_zammad_with_elasticsearch` to reconfigure your
+   installation for Elasticsearch use and rebuild the search index.
+
+You are now ready to continue your work.
+The rebuild of your search index can safely run during your work, but will
+cause a degraded search performance and may lead to temporarily not found
+data.

appendix/backup-and-restore/backup.rst

@@ -0,0 +1,49 @@
+Create Backup
+*************
+
+.. code-block:: sh
+
+   # Zammad backup started - Fri Jan 21 17:53:44 CET 2022!
+
+   creating file backup...
+    ... as full dump
+   creating postgresql backup...
+   Ensuring dump permissions ...
+
+   # Zammad backuped successfully - Fri Jan 21 17:53:57 CET 2022!
+
+*Sample backup process with default*
+:doc:`settings </appendix/backup-and-restore/configuration>`.
+
+--------------------------------------------------------------------------------
+
+.. note::
+
+   🤓 Before running your first backup, please have a look at
+   :doc:`/appendix/backup-and-restore/configuration`.
+
+In general, running a Zammad backup is as simple as running
+
+.. code-block:: sh
+
+   $ /opt/zammad/contrib/backup/zammad_backup.sh
+
+Please make sure to test the backup function manually with the user
+you're planning the backup first. This ensures that your backup really
+is running as expected.
+
+Remarks
+   | The backup script can be either run as ``zammad`` or ``root`` user.
+   | Stopping Zammad is not required (but suggested) technically, but may be in
+     your use case!
+   | (Keep in mind that a running Zammad instance keeps changing data which may
+     be an issue during long backup runs)
+
+
+.. hint::
+
+   **😖 Having trouble backing up?**
+
+   Have a look at the
+   :doc:`troubleshooting section </appendix/backup-and-restore/troubleshooting>`
+   to address your issues.

appendix/backup-and-restore/clear-the-cache.include.rst

@@ -0,0 +1,3 @@
+.. code-block:: sh
+
+   $ zammad run rails r "Cache.clear"

appendix/backup-and-restore/configuration.rst

@@ -0,0 +1,86 @@
+Backup configuration
+********************
+
+Before you can run either a backup or restoration, the scripts requires you
+to provide a configuration file. We're shipping a ``config.dist`` within the
+``/opt/zammad/contrib/backup`` directory which you can simply rename.
+
+To do so run the following commands as either ``root`` or ``zammad`` user.
+
+.. code-block:: sh
+
+   $ cd /opt/zammad/contrib/backup/
+   $ mv config.dist config
+
+If below default values are not working for you or your installation in general,
+this is the best moment to adjust the configuration file as needed. 
+
+After this you'll be ready to continue with either
+:doc:`creating your first backup </appendix/backup-and-restore/backup>` or
+:doc:`restoring an existing backup </appendix/backup-and-restore/backup>`.
+
+``BACKUP_DIR``
+   Default: ``/var/tmp/zammad_backup``
+
+   Tell the backup script where to write your backup files to.
+
+      .. warning::
+
+         Ensure that the user you're going to use for backing up Zammad
+         (either ``root`` or ``zammad`` by default) has enough permissions
+         to write into the target directory structure.
+
+   In case the directory is not available yet, the backup script will attempt
+   to create the directory.
+
+      .. hint::
+
+         Ensure to have enough space available on the backup location.
+         Zammad always creates full backups. While we do compress backups,
+         expect worst case ratios of 1 (no compression at all) depending
+         on your attachments!
+
+``HOLD_DAYS``
+   Default: ``10``
+
+   How many days should the backup script keep old backups?
+   This value contains 60 minutes grace period (so e.g. 10 days plus 1 hour)
+   for safety reasons.
+
+   Old backups are removed *before* creating the actual (current) backup.
+
+      .. note::
+
+         | ``0`` will keep the last 25 hours worth of backup
+         | ``-1`` will always remove all available backups
+           (aka only keep current backup)
+
+``FULL_FS_DUMP``
+   Default: ``yes`` (accepts: ``yes`` or ``no``)
+
+      .. note::
+
+         If you can't decide, our clear suggestion is setting this to ``no``.
+
+   Setting this option to ``no`` allows you to only backup usage data without
+   any environmental files from your old host. This allows you to backup your
+   Zammad database together with the attachments you've stored within the file
+   system.
+
+   Please refer `Storage Settings`_ to learn how to change the
+   storage location of your attachments.
+
+.. _Storage Settings:
+   https://admin-docs.zammad.org/en/latest/settings/system/storage.html
+
+``DEBUG``
+   Default: ``no`` (accepts: ``yes`` or ``no``)
+
+   Having issues and want to fiddle around? Setting this option to ``yes`` may
+   help you with this. It contains useful debug messages at strategic points.
+
+      .. warning::
+
+         This option potentially returns **sensitive** information to standard
+         out! *Do not* use this option in productive environments or ensure
+         to turn it *off after testing*.

appendix/backup-and-restore/console-command-note.include.rst

@@ -0,0 +1,7 @@
+.. note::
+
+   Keep in mind that docker-compose and source code installations do not know
+   ``zammad run``. Below commands show the package installation way, just remove
+   all ``zammad run`` parts from the commands and run them.
+
+   This means: ``zammad run rails c`` would be ``rails c``.