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