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