From f8c198709120cf94d9e7263d5979c4cf0dc95b67 Mon Sep 17 00:00:00 2001 From: Daniel Schadt Date: Mon, 18 Jul 2022 18:55:40 +0200 Subject: update documentation with new data dir --- doc/administration/backup.rst | 28 +++++++++++++++++++++------- doc/administration/configuration.rst | 10 ++++++++++ 2 files changed, 31 insertions(+), 7 deletions(-) (limited to 'doc/administration') 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 = 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 + `__ 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: -- cgit v1.2.3