start writing docs properly, not in the README

1 files changed, 67 insertions, 0 deletions

diff --git a/doc/administration/upgrading.rst b/doc/administration/upgrading.rst
new file mode 100644
index 0000000..4bdc656
--- /dev/null
+++ b/doc/administration/upgrading.rst
@@ -0,0 +1,67 @@
+Upgrading
+=========
+
+Fietsboek does not currently have an automated updater, however it is quite
+simple to update Fietsboek manually.
+
+.. warning::
+
+    Make sure to have backups of your user data ready in case the upgrade fails!
+
+.. note::
+
+    It is advised to stop the Fietsboek server during the backup process.
+
+Pulling the New Code
+--------------------
+
+First, we need to pull the new code. This step depends on the source that you
+have installed Fietsboek from. In the case that you use ``git``, this can be
+done in the following way:
+
+.. code:: bash
+
+    git pull
+    git checkout v42.0  # Put in the version that you want to update to here
+
+If you have downloaded an archive with the Fietsboek source, you need to
+download the archive with the new version and extract it somewhere.
+
+Installing the Python Module
+----------------------------
+
+Use ``pip`` to install the new version of the Fietsboek package, as well as any
+new additional dependencies:
+
+.. code:: bash
+
+    .venv/bin/pip install .
+
+This step is similar to the command that you used when installing Fietsboek
+initially.
+
+Note that removed dependencies are not automatically removed. It might be worth
+to start with a clean virtual environment from time to time to clear out old
+cruft.
+
+Upgrading the Database
+----------------------
+
+.. warning::
+
+   It cannot be stressed enough that you should have backups of your data. This
+   is your last chance.
+
+Some updates might change the database schema. Those updates come with database
+migrations that can adapt an existing database to the new schema. In order to
+do so, use ``alembic``:
+
+.. code:: bash
+
+    .venv/bin/alembic -c production.ini upgrade head
+
+Restarting Fietsboek
+--------------------
+
+You can now run Fietsboek again. This step depends on the method that you use
+to deploy Fietsboek.