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     <p>(As of 5.1 these options are completely gone.)</p>
 148
 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
 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
 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: -->