|
39
|
1 Upgrade Instructions
|
|
|
2 ====================
|
|
|
3
|
|
|
4 A Trac environment sometimes needs to be upgraded before it can be used with
|
|
|
5 a new version of Trac. This document describes the steps necessary to upgrade
|
|
|
6 an environment.
|
|
|
7
|
|
|
8 Note that Environment upgrades are not necessary for minor version releases
|
|
|
9 unless otherwise noted. For example, there's no need to upgrade a Trac
|
|
|
10 environment created with (or upgraded) 0.8.0 when installing 0.8.4 (or any
|
|
|
11 other 0.8.x release).
|
|
|
12
|
|
|
13 General Instructions
|
|
|
14 --------------------
|
|
|
15 Typically, there are four steps involved in upgrading to a newer version of
|
|
|
16 Trac:
|
|
|
17
|
|
|
18 1. Update the Trac Code
|
|
|
19
|
|
|
20 Get the new version of Trac, either by downloading an offical release package
|
|
|
21 or by checking it out from the Subversion repository.
|
|
|
22
|
|
|
23 If you have a source distribution, you need to run
|
|
|
24
|
|
|
25 python setup.py install
|
|
|
26
|
|
|
27 to install the new version. If you've downloaded the Windows installer, you
|
|
|
28 execute it, and so on.
|
|
|
29
|
|
|
30 In any case, if you're doing a major version upgrade (such as from 0.8 to
|
|
|
31 0.9), it is highly recommended that you first remove the existing Trac code.
|
|
|
32 To do this, you need to delete the `trac` directory from the Python
|
|
|
33 `lib/site-packages` directory. You may also want to remove the Trac `cgi-bin`,
|
|
|
34 `htdocs` and `templates` directories that are commonly found in a directory
|
|
|
35 called `share/trac` (the exact location depends on your platform).
|
|
|
36
|
|
|
37 2. Upgrade the Trac Environment
|
|
|
38
|
|
|
39 Unless noted otherwise, upgrading between major versions (such as 0.8 and
|
|
|
40 0.9) involves changes to the database schema, and possibly the layout of the
|
|
|
41 environment. Fortunately, Trac provides automated upgrade scripts to ease the
|
|
|
42 pain. These scripts are run via `trac-admin`:
|
|
|
43
|
|
|
44 trac-admin /path/to/projenv upgrade
|
|
|
45
|
|
|
46 This command will do nothing if the environment is already up-to-date.
|
|
|
47
|
|
|
48 3. Update the Trac Documentation
|
|
|
49
|
|
|
50 Every Trac environment includes a copy of the Trac documentation for the
|
|
|
51 installed version. As you probably want to keep the included documentation in
|
|
|
52 sync with the installed version of Trac, `trac-admin` provides a command to
|
|
|
53 upgrade the documentation:
|
|
|
54
|
|
|
55 trac-admin /path/to/projenv wiki upgrade
|
|
|
56
|
|
|
57 Note that this procedure will of course leave your `WikiStart` page intact.
|
|
|
58
|
|
|
59 4. Restart the Web Server
|
|
|
60
|
|
|
61 In order to reload the new Trac code you will need to restart your web
|
|
|
62 server (note this is not necessary for CGI).
|
|
|
63
|
|
|
64
|
|
|
65 The following sections discuss any extra actions that may need to be taken
|
|
|
66 to upgrade to specific versions of Trac.
|
|
|
67
|
|
|
68
|
|
|
69 From 0.9-beta to 0.9
|
|
|
70 --------------------
|
|
|
71
|
|
|
72 If inclusion of the static resources (style sheets, javascript, images) is not
|
|
|
73 working, check the value of the `htdocs_location` in trac.ini. For mod_python,
|
|
|
74 Tracd and FastCGI, you can simply remove the option altogether. For CGI, you
|
|
|
75 should fix it to point to the URL you mapped the Trac `htdocs` directory to.
|
|
|
76
|
|
|
77 If you've been using plugins with a beta release of Trac 0.9, or have
|
|
|
78 disabled some of the built-in components, you might have to update the rules
|
|
|
79 for disabling/enabling components in trac.ini. In particular, globally
|
|
|
80 installed plugins now need to be enabled explicitly. See the TracPlugins and
|
|
|
81 TracIni wiki pages for more information.
|
|
|
82
|
|
|
83 If you want to enable the display of all ticket changes in the timeline (the
|
|
|
84 Ticket Details option), you now have to explicitly enable that in trac.ini,
|
|
|
85 too:
|
|
|
86
|
|
|
87 [timeline]
|
|
|
88 ticket_show_details = true
|
|
|
89
|
|
|
90
|
|
|
91 From 0.8.x to 0.9
|
|
|
92 -----------------
|
|
|
93
|
|
|
94 mod_python users will need to change the name of the mod_python handler in
|
|
|
95 the Apache HTTPD configuration:
|
|
|
96
|
|
|
97 from: PythonHandler trac.ModPythonHandler
|
|
|
98 to: PythonHandler trac.web.modpython_frontend
|
|
|
99
|
|
|
100 If you have PySQLite 2.x installed, Trac will now try to open your SQLite
|
|
|
101 database using the SQLite 3.x file format. The database formats used by
|
|
|
102 SQLite 2.8.x and SQLite 3.x are incompatible. If you get an error like "file
|
|
|
103 is encrypted or is not a database" after upgrading, then you must convert
|
|
|
104 your database file.
|
|
|
105
|
|
|
106 To do this, you need to have both SQLite 2.8.x and SQLite 3.x installed (they
|
|
|
107 have different filenames so can coexist on the same system). Then use the
|
|
|
108 following commands:
|
|
|
109
|
|
|
110 mv trac.db trac2.db
|
|
|
111 sqlite trac2.db .dump | sqlite3 trac.db
|
|
|
112
|
|
|
113 After testing that the conversion was successful, the `trac2.db` file can be
|
|
|
114 deleted. For more information on the SQLite upgrade see
|
|
|
115 http://www.sqlite.org/version3.html.
|
|
|
116
|
|
|
117
|
|
|
118 From 0.7.x to 0.8
|
|
|
119 -----------------
|
|
|
120
|
|
|
121 0.8 adds a new roadmap feature which requires additional permissions. While a
|
|
|
122 fresh installation will by default grant `ROADMAP_VIEW` and `MILESTONE_VIEW`
|
|
|
123 permissions to anonymous, these permissions have to be granted manually when
|
|
|
124 upgrading:
|
|
|
125
|
|
|
126 trac-admin /path/to/projectenv permission add anonymous MILESTONE_VIEW
|
|
|
127 trac-admin /path/to/projectenv permission add anonymous ROADMAP_VIEW
|
|
|
128
|
|
|
129
|
|
|
130 From 0.6.x to 0.7
|
|
|
131 -----------------
|
|
|
132 Trac 0.7 introduced a new database format, requiring manual upgrade.
|
|
|
133
|
|
|
134 Previous versions of Trac stored wiki pages, ticket, reports, settings,
|
|
|
135 etc. in a single SQLite database file. Trac 0.7 replaces this file
|
|
|
136 with a new backend storage format; the 'Trac Environment', which is a
|
|
|
137 directory containing an SQLite database, a human-readable configuration file,
|
|
|
138 log-files and attachments.
|
|
|
139
|
|
|
140 Fear not though, old-style Trac databases can easily be converted to
|
|
|
141 Environments using the included `tracdb2env` program as follows:
|
|
|
142
|
|
|
143 tracdb2env /path/to/old/project.db /path/to/new/projectenv
|
|
|
144
|
|
|
145 `tracdb2env` will create a new environment and copy the information from the
|
|
|
146 old database to the new environment. The existing database will not be
|
|
|
147 modified.
|
|
|
148
|
|
|
149 You also need to update your apache configuration:
|
|
|
150
|
|
|
151 Change the line:
|
|
|
152
|
|
|
153 SetEnv TRAC_DB "/path/to/old/project.db"
|
|
|
154
|
|
|
155 to:
|
|
|
156
|
|
|
157 SetEnv TRAC_ENV "/path/to/new/projectenv"
|
|
|
158
|
|
|
159
|
|
|
160 ----
|
|
|
161
|
|
|
162 If you have trouble upgrading Trac, please ask questions on the mailing list:
|
|
|
163
|
|
|
164 <http://projects.edgewall.com/trac/wiki/MailingList>
|
|
|
165
|
|
|
166 Or for other support options, see:
|
|
|
167
|
|
|
168 <http://projects.edgewall.com/trac/wiki/TracSupport>
|
