1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
|
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.
.. tip::
If upgrading fails, try going in smaller steps, e.g. release by release. If
you upgrade over a big version span, the chances are bigger that unintended
interactions occur.
To do that, use ``git`` or ``pip`` to download specific versions of the
code instead of going for the latest one.
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 addition
to database migrations, some updates also modify the on-disk data that
Fietsboek stores.
Fietsboek comes with a handy tool that allows you to run the right database and
file migrations: ``fietsupdate``.
You can use the following command to upgrade to the latest installed version:
.. code:: bash
.venv/bin/fietsupdate update -c production.ini
Or you can view the status of your installation:
.. code:: bash
.venv/bin/fietsupdate status -c production.ini
.. note::
The ``fietsupdate`` tool is only there to run database migrations and other
update tasks. It does *not* retrieve or install the correct code, please
see the above sections to do that.
Restarting Fietsboek
--------------------
You can now run Fietsboek again. This step depends on the method that you use
to deploy Fietsboek.
Downgrading
===========
In some cases, it might be required that you uninstall an update to Fietsboek,
for example if it introduced a bug. Downgrading is possible and generally
consists of two steps:
1) Restore the old data format (backwards migration)
2) Restore the old code
.. warning::
As with updates, make sure you have backups of your important data ready!
Restoring Data: Backups
-----------------------
The preferred way to use the old data is by restoring a backup, see
:doc:`backup`. This method ensures that your data is original and prevents the
upgrade/downgrade process from inducing errors.
Restoring Data: Downgrading
---------------------------
If you do not have old backups of your data, you can use ``fietsupdate`` to
convert your data from the new format to the old one. Please note that the
upgrade process can not always be undone: If an update deletes data, even the
downgrade cannot fix it. In such cases, the only way to restore the data is
through a backup.
To use ``fietsupdate`` to downgrade your data, run the following command,
replacing ``VERSION`` with the version you want to downgrade to:
.. code:: bash
.venv/bin/fietsupdate downgrade -c production.ini VERSION
Restoring Code
--------------
Now that the data has been restored to the old state, you need to restore the
Fietsboek code to the old version. This works similarly to the update, with the
difference that you should download and install the version of Fietsboek that
you downgraded your data to.
If you use ``git``, you can check out old versions of the code by using ``git
checkout``.
After obtaining the old code, don't forget to install it into your virtual
environment!
|
