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