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