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

   1 * Upgrading DisOrder
   2
   3 The general procedure is:
   4
   5  * stop the old daemon:  /etc/init.d/disorder stop
   6  * back up your database directory (example below)
   7  * build and install the new version as described in the README.  Remember to
   8    install the new version of the web interface too.
   9  * update the configuration files (see below)
  10  * start the new daemon, e.g. with
  11      /etc/init.d/disorder start
  12
  13 The rest of this file describes things you must pay attention to when
  14 upgrading between particular versions.  Minor versions are not
  15 explicitly mentioned; a version number like 1.1 implicitly includes
  16 all 1.1.x versions.
  17
  18 * 2.0 -> 2.1
  19
  20 ** Authentication
  21
  22 Users are now stored in the database rather than in 'allow' directives in a
  23 private configuration file.  'allow' is still understood in this version, but
  24 is only used to populate the database on startup.  After the first (successful)
  25 run of the server the remaining 'allow' directives should be deleted.
  26
  27 'restrict' and 'trust' are replaced by a system of per-user rights.  The
  28 default user rights are based on the 'restrict' setting, and the rights of
  29 users created frow 'allow' directives preserve the meaning of 'trust', but
  30 after the first run you should remove these directives and (optionally) add a
  31 'default_rights' directive.
  32
  33 'allow', 'restrict' and 'trust' will stop working entirely in a future version
  34 but for now they will generate harmless error messages.  Remove them and the
  35 error messages will go away.
  36
  37 ** Other Server Configuration
  38
  39 Sensible defaults for 'stopword', 'player' and 'tracklength' are now built into
  40 the server.  If you haven't modified the values from the example or Debian
  41 configuration files then you can remove them.
  42
  43 'gap' now defaults to 0 seconds instead of 2.
  44
  45 ** Web Interface
  46
  47 The web interface no longer uses HTTP basic authentication and the web server
  48 configuration imposing access control on it should be removed.  Users now log
  49 in using their main DisOrder password and the one in the htpassed file is now
  50 obsolete.  You should revisit the web interface setup instructions in README
  51 from scratch.
  52
  53 * 1.4/1.5 -> 2.0
  54
  55 ** 'transform' and 'namepart' directives
  56
  57 'transform' has moved from the web options to the main configuration file, so
  58 that they can be used by other interfaces.  The syntax and semantics are
  59 unchanged.
  60
  61 More importantly however both 'transform' and 'namepart' are now optional, with
  62 sensible defaults being built in.  So if you were already using the default
  63 values you can just delete all instances of both.
  64
  65 See disorder_config(5) for the default values.  Hopefuly they will be suitable
  66 for many configurations.  Please do send feedback.
  67
  68 ** 'enabled' and 'random_enabled' directives
  69
  70 These have been removed.  Instead the state persists from one run of the server
  71 to the next.  If they appear in your configuration file they must be removed;
  72 the server will not start if they are present.
  73
  74 ** Database upgrade
  75
  76 It is strongly recommended that you back up your database before performing the
  77 upgrade.  For example, as root, with the server STOPPED:
  78   cd /var/disorder
  79   mkdir BACKUP
  80   cp -p * BACKUP
  81
  82 To restore, again as root:
  83   cd /var/disorder
  84   rm *
  85   cp -p BACKUP/* .
  86
  87 The first thing the server does when upgrading from 1.5 is run the
  88 disorder-dbupgrade program.  This is necessary to modify any non-ASCII track
  89 names to meet the latest version's stricter normalization practices.  The
  90 upgrade should succeed automatically; if not it should leave an error message
  91 in syslog.
  92
  93 * 1.3 -> 1.4
  94
  95 ** Raw Format Decoders
  96
  97 You will probably want reconfigure your install to use the new facilities
  98 (although the old way works fine).  See the example configuration file and
  99 README.raw for more details.
 100
 101 Depending on how your system is configured you may need to link the disorder
 102 libao driver into the right directory:
 103
 104    ln -s /usr/local/lib/ao/plugins-2/libdisorder.so /usr/lib/ao/plugins-2/.
 105
 106 * 1.2 -> 1.3
 107
 108 ** Server Environment
 109
 110 It is important that $sbindir is on the server's path.  The example init script
 111 guarantees this.  You may need to modify the installed one.  You will get
 112 "deadlock manager unexpectedly terminated" if you get this wrong.
 113
 114 ** namepart directives
 115
 116 These have changed in three ways.
 117
 118 Firstly they have changed to substitute in a more convenient way.  Instead of
 119 matches for the regexp being substituted back into the original track name, the
 120 replacement string now completely replaces it.  Given the usual uses of
 121 namepart, this is much more convenient.  If you've stuck with the defaults no
 122 changes should be needed for this.
 123
 124 Secondly they are matched against the track name with the collection root
 125 stripped off.
 126
 127 Finally you will need to add an extra line to your config file as follows for
 128 the new track aliasing mechanisms to work properly:
 129
 130 namepart        ext     "(\\.[a-zA-Z0-9]+)$"                   "$1"    *
 131
 132 * 1.1 -> 1.2
 133
 134 ** Web Interface Changes
 135
 136 The web interface now includes static content as well as templates.
 137 The static content must be given a name visible to HTTP clients which
 138 maps to its location in the real filesystem.
 139
 140 The README suggests using a rule in httpd.conf to make /static in the
 141 HTTP namespace point to /usr/local/share/disorder/static, which is
 142 where DisOrder installs its static content (by default).
 143 Alternatively you can set the url.static label to the base URL of the
 144 static content.
 145
 146 ** Configuration File Changes
 147
 148 The trackname-part web interface directive has now gone, and the
 149 options.trackname file with it.
 150
 151 It is replaced by a new namepart directive in the main configuration
 152 file.  This has exactly the same syntax as trackname-part, only the
 153 name and location have changed.
 154
 155 The reason for the change is to allow track name parsing to be
 156 centrally configured, rather than every interface to DisOrder having
 157 to implement it locally.
 158
 159 If you do not install new namepart directives into the main
 160 configuration file then track titles will show up blank.
 161
 162 If you do not remove the trackname-part directives from the web
 163 interface configuration then you will get error messages in the web
 164 server's error log.
 165
 166 Local Variables:
 167 mode:outline
 168 fill-column:79
 169 End: