update documentation with new data dir

2 files changed, 31 insertions, 7 deletions

diff --git a/doc/administration/backup.rst b/doc/administration/backup.rst
index 9566e38..3973298 100644
--- a/doc/administration/backup.rst
+++ b/doc/administration/backup.rst
@@ -15,10 +15,20 @@ case data is lost due unforseen reasons.
 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.
+The Fietsboek data lives in two places: Most of it is saved in the database,
+while track images and other "big files" are saved in the data directory.
+
+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.
+
+After backing up the database, you should back up the data directory with a
+tool of your choice, for example by using ``tar``, ``rsync`` or a proper backup
+tool like ``borg``:
+
+.. code:: bash
+
+    tar -czf backup.tar.gz path/to/data/dir
 
 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
@@ -42,7 +52,7 @@ Note those value in addition to your backup.
 Restore
 -------
 
-The restoration process works in three steps:
+The restoration process works in four steps:
 
 First, we ensure that we are on the correct Fietsboek version. If you are using
 ``git``, this can be done with ``git checkout``:
@@ -57,5 +67,9 @@ Then, we get the database schema to the right version:
 
     .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.
+Now, we can restore the data in the database. This step is dependent on the
+DBMS that you, therefore you should consult its documentation.
+
+Finally, we can restore the data directory. This step depends on how you chose
+to back up the data directory earlier. In the case of ``tar``, you can simply
+extract the archive to the right location.
diff --git a/doc/administration/configuration.rst b/doc/administration/configuration.rst
index 48afde1..3927540 100644
--- a/doc/administration/configuration.rst
+++ b/doc/administration/configuration.rst
@@ -35,6 +35,7 @@ Most of the configuration is in the ``[app:main]`` category and looks like this:
     session_key = <EDIT THIS>
 
     sqlalchemy.url = sqlite:///%(here)s/fietsboek.sqlite
+    fietsboek.data_dir = %(here)s/data
 
     retry.attempts = 3
 
@@ -51,6 +52,15 @@ Most of the configuration is in the ``[app:main]`` category and looks like this:
   creation of new accounts via the web interface, for example if you want to
   have a private instance. New accounts can always be created using the CLI
   management tool.
+* ``session_key`` should be set to a random string of characters. This is the
+  key used to sign session data, so it should not get into wrong hands!
+* ``sqlalchemy.url`` is the URL to the database. See the `SQLAlchemy
+  documentation
+  <https://docs.sqlalchemy.org/en/14/core/engines.html#database-urls>`__ for
+  more information.
+* ``fietsboek.data_dir`` sets the directory for data uploads. This directory
+  must be writable by the Fietsboek process, as Fietsboek will save track
+  images in there.
 * ``email.from`` sets the sender of emails, for example for account verifications.
 * ``email.smtp_url`` sets the URL of the SMTP server. The following formats are accepted: