Commit | Line | Data |
---|---|---|
2ea2b361 RK |
1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"> |
2 | <html> | |
3 | <head> | |
4 | <title>Upgrading DisOrder</title> | |
5 | <link rel=StyleSheet type="text/css" href="docs.css"> | |
6 | </head> | |
7 | <body> | |
8 | <h1>Upgrading DisOrder</h1> | |
9 | ||
10 | <ul> | |
11 | <li><a href="#deb">.deb Installs</a></li> | |
12 | <li><a href="#source">Source Installs</a></li> | |
13 | <li><a href="#ver">Version-Specific Details</a></li> | |
14 | </ul> | |
15 | ||
16 | <h2><a name="deb">.deb Installs</a></h2> | |
17 | ||
18 | <h3>Take A Backup</h3> | |
19 | ||
20 | <p>You should make a backup of DisOrder's databases before proceeding with | |
21 | any upgrade. You can generate a backup as follows:</p> | |
22 | ||
23 | <pre># disorder-dump --dump <i>PATH</i></pre> | |
24 | ||
25 | <p>where <i>PATH</i> is the filename to write the backup to.</p> | |
26 | ||
27 | <p>As of version 5.1, the Debian version of the server will take a daily | |
28 | backup of its databases to <tt>/var/lib/disorder/backups</tt>, so it should | |
29 | not be a disaster if you neglect this step in <i>subsequent</i> | |
30 | upgrades.</p> | |
31 | ||
32 | <h3>Install The New Packages</h3> | |
33 | ||
34 | <pre># dpkg -i *.deb</pre> | |
35 | ||
36 | <h3>Upgrade Databases</h3> | |
37 | ||
38 | <p>If you have changed version of <tt>libdb</tt> then the new one may not | |
39 | be compatible with the old one's file format. In this case the server will | |
40 | not start, causing the upgrade to fail. Remove the database files and | |
41 | restore from the backup you took above.</p> | |
42 | ||
43 | <pre># rm /var/lib/disorder/* | |
44 | # disorder-dump --restore PATH | |
45 | # dpkg --configure -a</pre> | |
46 | ||
47 | <h2><a name=source>Source Installs</a></h2> | |
48 | ||
49 | <h3>Take A Backup</h3> | |
50 | ||
51 | <p>You should make a backup of DisOrder's databases before proceeding with | |
52 | any upgrade. You can generate a backup as follows:</p> | |
53 | ||
54 | <pre># disorder-dump --dump PATH</pre> | |
55 | ||
56 | <p>where PATH is the filename to write the backup to.</p> | |
57 | ||
58 | <h3>Stop The Server</h3> | |
59 | ||
60 | <p>Linux:</p> | |
61 | ||
62 | <pre># /etc/init.d/disorder stop</pre> | |
63 | ||
64 | <p>Mac:</p> | |
65 | ||
66 | <pre># launchctl stop uk.org.greenend.rjk.disorder | |
67 | # launchctl unload /Library/LaunchDaemons/uk.org.greenend.rjk.disorder.plist</pre> | |
68 | ||
69 | <p>If you are feeling cautious you can also make an exact copy of the | |
70 | database files at this point (they are in | |
71 | <tt>/usr/local/var/disorder</tt>).</p> | |
72 | ||
73 | <h3>Build And Install The New Version</h3> | |
74 | ||
75 | <p>See the top-level <a href="README">README</a>.</p> | |
76 | ||
77 | <h3>Update Configuration Files</h3> | |
78 | ||
79 | <p>See version-specific information below.</p> | |
80 | ||
81 | <h3>Upgrade Databases</h3> | |
82 | ||
83 | <p>If you have changed version of <tt>libdb</tt> you may need to remove the | |
84 | database files and restore from the backup you took above.</p> | |
85 | ||
86 | <pre># rm /usr/local/var/disorder/* | |
87 | # disorder-dump --restore PATH</pre> | |
88 | ||
89 | <h3>Restart The Server</h3> | |
90 | ||
91 | <p>Linux:</p> | |
92 | ||
93 | <pre># /etc/init.d/disorder start</pre> | |
94 | ||
95 | <p>Mac:</p> | |
96 | ||
97 | <pre># cp examples/uk.org.greenend.rjk.disorder.plist /Library/LaunchDaemons/. | |
98 | # launchctl load /Library/LaunchDaemons | |
99 | # launchctl start uk.org.greenend.rjk.disorder</pre> | |
100 | ||
101 | <h1><a name=ver>Version-Specific Details</a></h1> | |
102 | ||
103 | <h2>4.x -> 5.0</h2> | |
104 | ||
105 | <h3>Web Confirmation Strings</h3> | |
106 | ||
107 | <p>The syntax of confirmation strings for online registrations has changed | |
108 | and old ones no longer work. This only affects users who registered before | |
109 | the upgrade but have not yet confirmed their login. You can delete such | |
110 | half-created users with 'disorder deluser USERNAME' (as an administrative | |
111 | user, for instance as root on the server) and they can start the | |
112 | registration process again.</p> | |
113 | ||
114 | <h3>Handling Of Configuration Changes</h3> | |
115 | ||
116 | <p>There is a new mechanism to ensure that the search database and aliases | |
117 | are reconstructed if any options that affect them change. Unfortunately | |
118 | this means that the reconstruction step always takes place on upgrade from | |
119 | 4.3 or earlier, as those versions don't record sufficient information for | |
120 | the server to tell whether it needs to reconstruct or not.</p> | |
121 | ||
122 | <p>The result will be a log message of the form:</p> | |
123 | ||
124 | <pre>new database parameter string dbparams-0-sha256:61609f3e6395ec8dee317ee216fe2848d70c249d347dd03c6a219441a13dd456 - removing old data</pre> | |
125 | ||
126 | <p>...and a slower rescan on startup. Subsequent restarts should not have | |
127 | this problem (unless of course you change a relevant option).</p> | |
128 | ||
129 | <h3>Deprecation Notices</h3> | |
130 | ||
131 | <p>The player <tt>--wait-for-device</tt> option is deprecated and will be | |
132 | removed in a future version.</p> | |
133 | ||
134 | <p>The 'lock' option no longer does anything. You must delete it from any | |
135 | configuration files that contain it. The full set of deprecated options | |
136 | is:</p> | |
137 | ||
138 | <ul> | |
139 | <li>allow</li> | |
140 | <li>gap</li> | |
141 | <li>lock</li> | |
142 | <li>prefsync</li> | |
143 | <li>restrict</li> | |
144 | <li>trust</li> | |
145 | </ul> | |
146 | ||
657fdb79 RK |
147 | <p>(As of 5.1 these options are completely gone.)</p> |
148 | ||
2ea2b361 RK |
149 | <h2>3.0 -> 4.x</h2> |
150 | ||
151 | <p>If you customized any of the templates, you will pretty much have to | |
152 | start from scratch as the web interface has been rewritten. See | |
153 | disorder.cgi(8) for a starting point.</p> | |
154 | ||
155 | <p>The 'gap' directive will no longer work. You must delete it from any | |
156 | configuration files that contain it.</p> | |
157 | ||
158 | <p>You may prefer to remove any 'smtp_server' directive you have, as the | |
159 | web interface will now use the local sendmail executable if available.</p> | |
160 | ||
161 | <p>If you want to be able to do use management over non-local connections | |
162 | (thereby potentially exposing passwords!) you must set 'remote_userman' to | |
163 | 'yes'.</p> | |
164 | ||
165 | <h2>2.0 -> 3.0</h2> | |
166 | ||
167 | <h3>Authentication</h3> | |
168 | ||
169 | <p>Users are now stored in the database rather than in 'allow' directives | |
170 | in a private configuration file. 'allow' is still understood in this | |
171 | version, but is only used to populate the database on startup. After the | |
172 | first (successful) run of the server the remaining 'allow' directives | |
173 | should be deleted.</p> | |
174 | ||
175 | <p>'restrict' and 'trust' are replaced by a system of per-user rights. The | |
176 | default user rights are based on the 'restrict' setting, and the rights of | |
177 | users created frow 'allow' directives preserve the meaning of 'trust', but | |
178 | after the first run you should remove these directives and (optionally) add | |
179 | a 'default_rights' directive.</p> | |
180 | ||
181 | <p>'allow', 'restrict' and 'trust' will stop working entirely in a future | |
182 | version but for now they will generate harmless error messages. Remove | |
183 | them and the error messages will go away.</p> | |
184 | ||
657fdb79 RK |
185 | <p>(Note: these options, and the code for upgrading old users, has been |
186 | removed entirely in release 5.1. You must either manually re-create your | |
187 | users, or upgrade via 5.0.3.)</p> | |
188 | ||
2ea2b361 RK |
189 | <p>See README for new setup instructions for the web interface.</p> |
190 | ||
191 | <h3>Other Server Configuration</h3> | |
192 | ||
193 | <p>Sensible defaults for 'stopword', 'player' and 'tracklength' are now | |
194 | built into the server. If you haven't modified the values from the example | |
195 | or Debian configuration files then you can remove them.</p> | |
196 | ||
197 | <p>'gap' now defaults to 0 seconds instead of 2.</p> | |
198 | ||
199 | <p>The sound output API is now configured with the 'api' command although | |
200 | 'speaker_backend' still works. If you use 'api alsa' then you may need to | |
201 | change your 'mixer' and 'channel' settings.</p> | |
202 | ||
203 | <h3>Web Interface</h3> | |
204 | ||
205 | <p>The web interface no longer uses HTTP basic authentication and the web | |
206 | server configuration imposing access control on it should be removed. | |
207 | Users now log in using their main DisOrder password and the one in the | |
208 | htpassed file is now obsolete. You should revisit the web interface setup | |
209 | instructions in README from scratch.</p> | |
210 | ||
211 | <p>As part of this, the DisOrder URL has changed from (e.g.)</p> | |
212 | ||
213 | <pre>http://yourserver/cgi-bin/disorder/disorder</pre> | |
214 | ||
215 | <p>to just</p> | |
216 | ||
217 | <pre>http://yourserver/cgi-bin/disorder</pre> | |
218 | ||
219 | <h3>Checklist</h3> | |
220 | ||
221 | <ul> | |
222 | <li>delete default 'stopword', 'player' and 'tracklength' directives</li> | |
223 | <li>set 'gap' if you want a non-0 inter-track gap</li> | |
224 | <li>set 'api' and maybe 'mixer' and 'channel'</li> | |
225 | <li>perhaps add 'default_rights' directive</li> | |
226 | <li>delete 'allow', 'restrict' and 'trust' directives after first run</li> | |
227 | <li>follow new web interface setup in README</li> | |
228 | </ul> | |
229 | ||
230 | <h2>1.4/1.5 -> 2.0</h2> | |
231 | ||
232 | <h3>'transform' and 'namepart' directives</h3> | |
233 | ||
234 | <p>'transform' has moved from the web options to the main configuration | |
235 | file, so that they can be used by other interfaces. The syntax and | |
236 | semantics are unchanged.</p> | |
237 | ||
238 | <p>More importantly however both 'transform' and 'namepart' are now | |
239 | optional, with sensible defaults being built in. So if you were already | |
240 | using the default values you can just delete all instances of both.</p> | |
241 | ||
242 | <p>See disorder_config(5) for the default values. Hopefuly they will be | |
243 | suitable for many configurations. Please do send feedback.</p> | |
244 | ||
245 | <h3>'enabled' and 'random_enabled' directives</h3> | |
246 | ||
247 | <p>These have been removed. Instead the state persists from one run of the | |
248 | server to the next. If they appear in your configuration file they must be | |
249 | removed; the server will not start if they are present.</p> | |
250 | ||
251 | <h3>Database upgrade</h3> | |
252 | ||
253 | <p>It is strongly recommended that you back up your database before | |
254 | performing the upgrade. For example, as root, with the server STOPPED:</p> | |
255 | ||
256 | <pre># cd /var/disorder | |
257 | # mkdir BACKUP | |
258 | # cp -p * BACKUP</pre> | |
259 | ||
260 | <p>To restore, again as root:</p> | |
261 | <pre># cd /var/disorder | |
262 | # rm * | |
263 | # cp -p BACKUP/* .</pre> | |
264 | ||
265 | <p>The first thing the server does when upgrading from 1.5 is run the | |
266 | disorder-dbupgrade program. This is necessary to modify any non-ASCII | |
267 | track names to meet the latest version's stricter normalization practices. | |
268 | The upgrade should succeed automtically; if not it should leave an error | |
269 | message in syslog.</p> | |
270 | ||
271 | <h2>1.3 -> 1.4</h2> | |
272 | ||
273 | <h3>Raw Format Decoders</h3> | |
274 | ||
275 | <p>You will probably want reconfigure your install to use the new | |
276 | facilities (although the old way works fine). See the example | |
277 | configuration file and README.raw for more details.</p> | |
278 | ||
279 | <p>Depending on how your system is configured you may need to link the | |
280 | disorder libao driver into the right directory:</p> | |
281 | ||
282 | <pre># ln -s /usr/local/lib/ao/plugins-2/libdisorder.so /usr/lib/ao/plugins-2/.</pre> | |
283 | ||
284 | <h2>1.2 -> 1.3</h2> | |
285 | ||
286 | <h3>Server Environment</h3> | |
287 | ||
288 | <p>It is important that $sbindir is on the server's path. The example init | |
289 | script guarantees this. You may need to modify the installed one. You | |
290 | will get "deadlock manager unexpectedly terminated" if you get this | |
291 | wrong.</p> | |
292 | ||
293 | <h3>namepart directives</h3> | |
294 | ||
295 | <p>These have changed in three ways.</p> | |
296 | ||
297 | <p>Firstly they have changed to substitute in a more convenient way. | |
298 | Instead of matches for the regexp being substituted back into the original | |
299 | track name, the replacement string now completely replaces it. Given the | |
300 | usual uses of namepart, this is much more convenient. If you've stuck with | |
301 | the defaults no changes should be needed for this.</p> | |
302 | ||
303 | <p>Secondly they are matched against the track name with the collection | |
304 | root stripped off.</p> | |
305 | ||
306 | <p>Finally you will need to add an extra line to your config file as | |
307 | follows for the new track aliasing mechanisms to work properly:</p> | |
308 | ||
309 | <pre>namepart ext "(\\.[a-zA-Z0-9]+)$" "$1" *</pre> | |
310 | ||
311 | <h2>1.1 -> 1.2</h2> | |
312 | ||
313 | <h3>Web Interface Changes</h3> | |
314 | ||
315 | <p>The web interface now includes static content as well as templates. The | |
316 | static content must be given a name visible to HTTP clients which maps to | |
317 | its location in the real filesystem.</p> | |
318 | ||
319 | <p>The README suggests using a rule in httpd.conf to make /static in the | |
320 | HTTP namespace point to /usr/local/share/disorder/static, which is where | |
321 | DisOrder installs its static content (by default). Alternatively you can | |
322 | set the url.static label to the base URL of the static content.</p> | |
323 | ||
324 | <h3>Configuration File Changes</h3> | |
325 | ||
326 | <p>The trackname-part web interface directive has now gone, and the | |
327 | options.trackname file with it.</p> | |
328 | ||
329 | <p>It is replaced by a new namepart directive in the main configuration | |
330 | file. This has exactly the same syntax as trackname-part, only the name | |
331 | and location have changed.</p> | |
332 | ||
333 | <p>The reason for the change is to allow track name parsing to be centrally | |
334 | configured, rather than every interface to DisOrder having to implement it | |
335 | locally.</p> | |
336 | ||
337 | <p>If you do not install new namepart directives into the main | |
338 | configuration file then track titles will show up blank.</p> | |
339 | ||
340 | <p>If you do not remove the trackname-part directives from the web | |
341 | interface configuration then you will get error messages in the web | |
342 | server's error log.</p> | |
343 | ||
344 | </body> | |
345 | </html> | |
346 | ||
347 | <!-- Local Variables: --> | |
348 | <!-- fill-column:79 --> | |
349 | <!-- End: --> |