start writing docs properly, not in the README

1 files changed, 61 insertions, 0 deletions

diff --git a/doc/administration/backup.rst b/doc/administration/backup.rst
new file mode 100644
index 0000000..9566e38
--- /dev/null
+++ b/doc/administration/backup.rst
@@ -0,0 +1,61 @@
+Backup & Restore
+================
+
+A well-maintained Fietsboek instance should have regular backups configured in
+case data is lost due unforseen reasons.
+
+.. note::
+
+    As a rule of thumb: A backup that you haven't restored is not a backup!
+
+    Part of the backup process is to ensure that the backups actually contain
+    the necessary data and that the restoration process works. Make sure to
+    test your backups on a separate installation of Fietsboek.
+
+Backup
+------
+
+All of the Fietsboek data is contained in the database. You should refer to the
+manual of your DBMS to see what the procedure for a backup is. Using the
+preferred way for your DBMS ensures that your backup represents a consistent
+state of the database.
+
+In addition to the actual data, you should also note down the Fietsboek version
+and the database schema version, as backups can only be restored to the same
+version!
+
+To view the fietsboek version in case you are using ``git``, you can use the
+following command:
+
+.. code:: bash
+
+    git rev-parse HEAD
+
+To view the database schema version, use ``alembic``:
+
+.. code:: bash
+
+    .venv/bin/alembic -c development.ini current
+
+Note those value in addition to your backup.
+
+Restore
+-------
+
+The restoration process works in three steps:
+
+First, we ensure that we are on the correct Fietsboek version. If you are using
+``git``, this can be done with ``git checkout``:
+
+.. code:: bash
+
+    git checkout NOTED_GIT_VERSION_HERE
+
+Then, we get the database schema to the right version:
+
+.. code:: bash
+
+    .venv/bin/alembic -c production.ini upgrade NOTED_ALEMBIC_VERSION_HERE
+
+Finally, we can restore the data. This step is dependent on the DBMS that you,
+therefore you should consult its documentation.