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