annotate docs/upgrade.rst @ 5978:97bbc2824b32

tests: add basic test for mark_all_read action of notifications Adds test coverage for c7dc1c7ace67.
author Konstantin Veretennicov <kveretennicov@gmail.com>
date Wed, 15 Jun 2016 23:38:57 +0200
parents 8075ec3d0233
children 0b6d2ca7175f
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
5954
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
1 .. _upgrade:
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
2
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
3 ===================
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
4 Upgrading Kallithea
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
5 ===================
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
6
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
7 This describes the process for upgrading Kallithea, independently of the
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
8 Kallithea installation method.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
9
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
10
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
11 1. Stop the Kallithea web application
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
12 -------------------------------------
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
13
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
14 This step depends entirely on the web server software used to serve
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
15 Kallithea, but in any case, Kallithea should not be running during
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
16 the upgrade.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
17
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
18 .. note::
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
19 If you're using Celery, make sure you stop all instances during the
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
20 upgrade.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
21
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
22
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
23 2. Create a backup of both database and configuration
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
24 -----------------------------------------------------
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
25
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
26 You are of course strongly recommended to make backups regularly, but it
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
27 is *especially* important to make a full database and configuration
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
28 backup before performing a Kallithea upgrade.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
29
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
30 Back up your configuration
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
31 ^^^^^^^^^^^^^^^^^^^^^^^^^^
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
32
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
33 Make a copy of your Kallithea configuration (``.ini``) file.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
34
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
35 If you are using :ref:`rcextensions <customization>`, you should also
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
36 make a copy of the entire ``rcextensions`` directory.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
37
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
38 Back up your database
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
39 ^^^^^^^^^^^^^^^^^^^^^
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
40
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
41 If using SQLite, simply make a copy of the Kallithea database (``.db``)
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
42 file.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
43
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
44 If using PostgreSQL, please consult the documentation for the ``pg_dump``
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
45 utility.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
46
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
47 If using MySQL, please consult the documentation for the ``mysqldump``
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
48 utility.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
49
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
50 Look for ``sqlalchemy.db1.url`` in your configuration file to determine
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
51 database type, settings, location, etc.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
52
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
53
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
54 3. Activate the Kallithea virtual environment (if any)
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
55 ------------------------------------------------------
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
56
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
57 Verify that you are using the Python environment that you originally
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
58 installed Kallithea in by running::
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
59
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
60 pip freeze
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
61
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
62 This will list all packages installed in the current environment. If
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
63 Kallithea isn't listed, activate the correct virtual environment.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
64 See the appropriate installation page for details.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
65
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
66
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
67 4. Install new version of Kallithea
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
68 -----------------------------------
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
69
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
70 Please refer to the instructions for the installation method you
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
71 originally used to install Kallithea.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
72
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
73 If you originally installed using pip, it is as simple as::
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
74
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
75 pip install --upgrade kallithea
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
76
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
77 If you originally installed from version control, it is as simple as::
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
78
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
79 cd my-kallithea-clone
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
80 hg pull -u
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
81 pip install -e .
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
82
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
83
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
84 5. Upgrade your configuration
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
85 -----------------------------
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
86
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
87 Run the following command to upgrade your configuration (``.ini``) file::
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
88
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
89 paster make-config Kallithea my.ini
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
90
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
91 This will display any changes made by the new version of Kallithea to your
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
92 current configuration, and attempt an automatic merge. It is recommended
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
93 that you check the contents after the merge.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
94
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
95 .. note::
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
96 Please always make sure your ``.ini`` files are up to date. Errors
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
97 can often be caused by missing parameters added in new versions.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
98
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
99
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
100 6. Upgrade your database
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
101 ------------------------
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
102
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
103 To do this simply run::
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
104
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
105 paster upgrade-db my.ini
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
106
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
107 This will upgrade the schema and update some of the defaults in the database,
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
108 and will always recheck the settings of the application, if there are no new
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
109 options that need to be set.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
110
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
111 .. note::
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
112 The DB schema upgrade library has some limitations and can sometimes fail if you try to
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
113 upgrade from older major releases. In such a case simply run upgrades sequentially, e.g.,
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
114 upgrading from 0.1.X to 0.3.X should be done like this: 0.1.X. > 0.2.X > 0.3.X.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
115 You can always specify what version of Kallithea you want to install e.g. using pip:
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
116 ``pip install Kallithea==0.2``
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
117
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
118
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
119 7. Rebuild the Whoosh full-text index
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
120 -------------------------------------
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
121
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
122 It is recommended that you rebuild the Whoosh index after upgrading since
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
123 new Whoosh versions can introduce incompatible index changes.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
124
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
125
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
126 8. Start the Kallithea web application
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
127 --------------------------------------
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
128
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
129 This step once again depends entirely on the web server software used to
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
130 serve Kallithea.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
131
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
132 Before starting the new version of Kallithea, you may find it helpful to
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
133 clear out your log file so that new errors are readily apparent.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
134
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
135 .. note::
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
136 If you're using Celery, make sure you restart all instances of it after
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
137 upgrade.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
138
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
139
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
140 .. _virtualenv: http://pypi.python.org/pypi/virtualenv