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