chiark - git - mdw - disorder/blob - README.upgrades.html

   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
 147     <h2>3.0 -> 4.x</h2>
 148
 149     <p>If you customized any of the templates, you will pretty much have to
 150     start from scratch as the web interface has been rewritten.  See
 151     disorder.cgi(8) for a starting point.</p>
 152
 153     <p>The 'gap' directive will no longer work.  You must delete it from any
 154     configuration files that contain it.</p>
 155
 156     <p>You may prefer to remove any 'smtp_server' directive you have, as the
 157     web interface will now use the local sendmail executable if available.</p>
 158
 159     <p>If you want to be able to do use management over non-local connections
 160     (thereby potentially exposing passwords!) you must set 'remote_userman' to
 161     'yes'.</p>
 162
 163     <h2>2.0 -> 3.0</h2>
 164
 165     <h3>Authentication</h3>
 166
 167     <p>Users are now stored in the database rather than in 'allow' directives
 168     in a private configuration file.  'allow' is still understood in this
 169     version, but is only used to populate the database on startup.  After the
 170     first (successful) run of the server the remaining 'allow' directives
 171     should be deleted.</p>
 172
 173     <p>'restrict' and 'trust' are replaced by a system of per-user rights.  The
 174     default user rights are based on the 'restrict' setting, and the rights of
 175     users created frow 'allow' directives preserve the meaning of 'trust', but
 176     after the first run you should remove these directives and (optionally) add
 177     a 'default_rights' directive.</p>
 178
 179     <p>'allow', 'restrict' and 'trust' will stop working entirely in a future
 180     version but for now they will generate harmless error messages.  Remove
 181     them and the error messages will go away.</p>
 182
 183     <p>See README for new setup instructions for the web interface.</p>
 184
 185     <h3>Other Server Configuration</h3>
 186
 187     <p>Sensible defaults for 'stopword', 'player' and 'tracklength' are now
 188     built into the server.  If you haven't modified the values from the example
 189     or Debian configuration files then you can remove them.</p>
 190
 191     <p>'gap' now defaults to 0 seconds instead of 2.</p>
 192
 193     <p>The sound output API is now configured with the 'api' command although
 194     'speaker_backend' still works.  If you use 'api alsa' then you may need to
 195     change your 'mixer' and 'channel' settings.</p>
 196
 197     <h3>Web Interface</h3>
 198
 199     <p>The web interface no longer uses HTTP basic authentication and the web
 200     server configuration imposing access control on it should be removed.
 201     Users now log in using their main DisOrder password and the one in the
 202     htpassed file is now obsolete.  You should revisit the web interface setup
 203     instructions in README from scratch.</p>
 204
 205     <p>As part of this, the DisOrder URL has changed from (e.g.)</p>
 206
 207     <pre>http://yourserver/cgi-bin/disorder/disorder</pre>
 208
 209     <p>to just</p>
 210
 211     <pre>http://yourserver/cgi-bin/disorder</pre>
 212
 213     <h3>Checklist</h3>
 214
 215     <ul>
 216     <li>delete default 'stopword', 'player' and 'tracklength' directives</li>
 217     <li>set 'gap' if you want a non-0 inter-track gap</li>
 218     <li>set 'api' and maybe 'mixer' and 'channel'</li>
 219     <li>perhaps add 'default_rights' directive</li>
 220     <li>delete 'allow', 'restrict' and 'trust' directives after first run</li>
 221     <li>follow new web interface setup in README</li>
 222         </ul>
 223
 224     <h2>1.4/1.5 -> 2.0</h2>
 225
 226     <h3>'transform' and 'namepart' directives</h3>
 227
 228     <p>'transform' has moved from the web options to the main configuration
 229     file, so that they can be used by other interfaces.  The syntax and
 230     semantics are unchanged.</p>
 231
 232     <p>More importantly however both 'transform' and 'namepart' are now
 233     optional, with sensible defaults being built in.  So if you were already
 234     using the default values you can just delete all instances of both.</p>
 235
 236     <p>See disorder_config(5) for the default values.  Hopefuly they will be
 237     suitable for many configurations.  Please do send feedback.</p>
 238
 239     <h3>'enabled' and 'random_enabled' directives</h3>
 240
 241     <p>These have been removed.  Instead the state persists from one run of the
 242     server to the next.  If they appear in your configuration file they must be
 243     removed; the server will not start if they are present.</p>
 244
 245     <h3>Database upgrade</h3>
 246
 247     <p>It is strongly recommended that you back up your database before
 248     performing the upgrade.  For example, as root, with the server STOPPED:</p>
 249
 250     <pre># cd /var/disorder
 251 # mkdir BACKUP
 252 # cp -p * BACKUP</pre>
 253
 254     <p>To restore, again as root:</p>
 255     <pre># cd /var/disorder
 256 # rm *
 257 # cp -p BACKUP/* .</pre>
 258
 259     <p>The first thing the server does when upgrading from 1.5 is run the
 260     disorder-dbupgrade program.  This is necessary to modify any non-ASCII
 261     track names to meet the latest version's stricter normalization practices.
 262     The upgrade should succeed automtically; if not it should leave an error
 263     message in syslog.</p>
 264
 265     <h2>1.3 -> 1.4</h2>
 266
 267     <h3>Raw Format Decoders</h3>
 268
 269     <p>You will probably want reconfigure your install to use the new
 270     facilities (although the old way works fine).  See the example
 271     configuration file and README.raw for more details.</p>
 272
 273     <p>Depending on how your system is configured you may need to link the
 274     disorder libao driver into the right directory:</p>
 275
 276     <pre># ln -s /usr/local/lib/ao/plugins-2/libdisorder.so /usr/lib/ao/plugins-2/.</pre>
 277
 278     <h2>1.2 -> 1.3</h2>
 279
 280     <h3>Server Environment</h3>
 281
 282     <p>It is important that $sbindir is on the server's path.  The example init
 283     script guarantees this.  You may need to modify the installed one.  You
 284     will get "deadlock manager unexpectedly terminated" if you get this
 285     wrong.</p>
 286
 287     <h3>namepart directives</h3>
 288
 289     <p>These have changed in three ways.</p>
 290
 291     <p>Firstly they have changed to substitute in a more convenient way.
 292     Instead of matches for the regexp being substituted back into the original
 293     track name, the replacement string now completely replaces it.  Given the
 294     usual uses of namepart, this is much more convenient.  If you've stuck with
 295     the defaults no changes should be needed for this.</p>
 296
 297     <p>Secondly they are matched against the track name with the collection
 298     root stripped off.</p>
 299
 300     <p>Finally you will need to add an extra line to your config file as
 301     follows for the new track aliasing mechanisms to work properly:</p>
 302
 303     <pre>namepart        ext     "(\\.[a-zA-Z0-9]+)$"                   "$1"    *</pre>
 304
 305     <h2>1.1 -> 1.2</h2>
 306
 307     <h3>Web Interface Changes</h3>
 308
 309     <p>The web interface now includes static content as well as templates.  The
 310     static content must be given a name visible to HTTP clients which maps to
 311     its location in the real filesystem.</p>
 312
 313     <p>The README suggests using a rule in httpd.conf to make /static in the
 314     HTTP namespace point to /usr/local/share/disorder/static, which is where
 315     DisOrder installs its static content (by default).  Alternatively you can
 316     set the url.static label to the base URL of the static content.</p>
 317
 318     <h3>Configuration File Changes</h3>
 319
 320     <p>The trackname-part web interface directive has now gone, and the
 321     options.trackname file with it.</p>
 322
 323     <p>It is replaced by a new namepart directive in the main configuration
 324     file.  This has exactly the same syntax as trackname-part, only the name
 325     and location have changed.</p>
 326
 327     <p>The reason for the change is to allow track name parsing to be centrally
 328     configured, rather than every interface to DisOrder having to implement it
 329     locally.</p>
 330
 331     <p>If you do not install new namepart directives into the main
 332     configuration file then track titles will show up blank.</p>
 333
 334     <p>If you do not remove the trackname-part directives from the web
 335     interface configuration then you will get error messages in the web
 336     server's error log.</p>
 337
 338   </body>
 339 </html>
 340
 341 <!-- Local Variables: -->
 342 <!-- fill-column:79 -->
 343 <!-- End: -->