chiark / gitweb /
Leave a bit of headroom above test port number, since we go at least
[disorder] / 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 * 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: