Commit | Line | Data |
---|---|---|
460b9539 | 1 | * Upgrading DisOrder |
2 | ||
3 | The 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 | ||
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 | ||
ad884aa5 | 18 | If 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 | |
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 | ||
7e4d1dfa RK |
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 | ||
8c37e83b RK |
47 | The player --wait-for-device option is deprecated and will be removed in a |
48 | future version. | |
49 | ||
7e4d1dfa | 50 | The 'lock' option no longer does anything. You must delete it from any |
317dc3e8 RK |
51 | configuration 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 | |
61 | If you customized any of the templates, you will pretty much have to start from | |
62 | scratch as the web interface has been rewritten. See disorder.cgi(8) for a | |
63 | starting point. | |
64 | ||
65 | The 'gap' directive will no longer work. You must delete it from any | |
66 | configuration files that contain it. | |
67 | ||
68 | You may prefer to remove any 'smtp_server' directive you have, as the web | |
69 | interface will now use the local sendmail executable if available. | |
70 | ||
71 | If you want to be able to do use management over non-local connections (thereby | |
72 | potentially exposing passwords!) you must set 'remote_userman' to 'yes'. | |
73 | ||
5aff007d | 74 | * 2.0 -> 3.0 |
f0feb22e RK |
75 | |
76 | ** Authentication | |
77 | ||
78 | Users are now stored in the database rather than in 'allow' directives in a | |
79 | private configuration file. 'allow' is still understood in this version, but | |
80 | is only used to populate the database on startup. After the first (successful) | |
04e1fa7c | 81 | run 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 |
84 | default user rights are based on the 'restrict' setting, and the rights of | |
85 | users created frow 'allow' directives preserve the meaning of 'trust', but | |
86 | after 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 |
90 | but for now they will generate harmless error messages. Remove them and the |
91 | error messages will go away. | |
92 | ||
ad884aa5 | 93 | See README for new setup instructions for the web interface. |
94 | ||
1cf4ef2f RK |
95 | ** Other Server Configuration |
96 | ||
97 | Sensible defaults for 'stopword', 'player' and 'tracklength' are now built into | |
98 | the server. If you haven't modified the values from the example or Debian | |
99 | configuration files then you can remove them. | |
100 | ||
101 | 'gap' now defaults to 0 seconds instead of 2. | |
f0feb22e | 102 | |
ad884aa5 | 103 | The 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 | |
105 | change your 'mixer' and 'channel' settings. | |
106 | ||
d84bf422 | 107 | ** Web Interface |
108 | ||
109 | The web interface no longer uses HTTP basic authentication and the web server | |
110 | configuration imposing access control on it should be removed. Users now log | |
111 | in using their main DisOrder password and the one in the htpassed file is now | |
1cf4ef2f RK |
112 | obsolete. You should revisit the web interface setup instructions in README |
113 | from scratch. | |
d84bf422 | 114 | |
4fb2cada RK |
115 | As part of this, the DisOrder URL has changed from (e.g.) |
116 | ||
117 | http://yourserver/cgi-bin/disorder/disorder | |
118 | ||
119 | to 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 |
137 | that they can be used by other interfaces. The syntax and semantics are | |
138 | unchanged. | |
139 | ||
140 | More importantly however both 'transform' and 'namepart' are now optional, with | |
141 | sensible defaults being built in. So if you were already using the default | |
142 | values you can just delete all instances of both. | |
143 | ||
144 | See disorder_config(5) for the default values. Hopefuly they will be suitable | |
145 | for many configurations. Please do send feedback. | |
146 | ||
147 | ** 'enabled' and 'random_enabled' directives | |
148 | ||
149 | These have been removed. Instead the state persists from one run of the server | |
150 | to the next. If they appear in your configuration file they must be removed; | |
151 | the server will not start if they are present. | |
152 | ||
153 | ** Database upgrade | |
92afc09e RK |
154 | |
155 | It is strongly recommended that you back up your database before performing the | |
156 | upgrade. For example, as root, with the server STOPPED: | |
157 | cd /var/disorder | |
158 | mkdir BACKUP | |
159 | cp -p * BACKUP | |
160 | ||
161 | To restore, again as root: | |
162 | cd /var/disorder | |
163 | rm * | |
164 | cp -p BACKUP/* . | |
460b9539 | 165 | |
5f5fc693 RK |
166 | The first thing the server does when upgrading from 1.5 is run the |
167 | disorder-dbupgrade program. This is necessary to modify any non-ASCII track | |
168 | names to meet the latest version's stricter normalization practices. The | |
169 | upgrade should succeed automatically; if not it should leave an error message | |
170 | in syslog. | |
460b9539 | 171 | |
172 | * 1.3 -> 1.4 | |
173 | ||
174 | ** Raw Format Decoders | |
175 | ||
176 | You will probably want reconfigure your install to use the new facilities | |
177 | (although the old way works fine). See the example configuration file and | |
178 | README.raw for more details. | |
179 | ||
180 | Depending on how your system is configured you may need to link the disorder | |
181 | libao 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 | ||
189 | It is important that $sbindir is on the server's path. The example init script | |
190 | guarantees 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 | ||
195 | These have changed in three ways. | |
196 | ||
197 | Firstly they have changed to substitute in a more convenient way. Instead of | |
198 | matches for the regexp being substituted back into the original track name, the | |
199 | replacement string now completely replaces it. Given the usual uses of | |
200 | namepart, this is much more convenient. If you've stuck with the defaults no | |
201 | changes should be needed for this. | |
202 | ||
203 | Secondly they are matched against the track name with the collection root | |
204 | stripped off. | |
205 | ||
206 | Finally you will need to add an extra line to your config file as follows for | |
207 | the new track aliasing mechanisms to work properly: | |
208 | ||
209 | namepart ext "(\\.[a-zA-Z0-9]+)$" "$1" * | |
210 | ||
211 | * 1.1 -> 1.2 | |
212 | ||
213 | ** Web Interface Changes | |
214 | ||
215 | The web interface now includes static content as well as templates. | |
216 | The static content must be given a name visible to HTTP clients which | |
217 | maps to its location in the real filesystem. | |
218 | ||
219 | The README suggests using a rule in httpd.conf to make /static in the | |
220 | HTTP namespace point to /usr/local/share/disorder/static, which is | |
221 | where DisOrder installs its static content (by default). | |
222 | Alternatively you can set the url.static label to the base URL of the | |
223 | static content. | |
224 | ||
225 | ** Configuration File Changes | |
226 | ||
227 | The trackname-part web interface directive has now gone, and the | |
228 | options.trackname file with it. | |
229 | ||
230 | It is replaced by a new namepart directive in the main configuration | |
231 | file. This has exactly the same syntax as trackname-part, only the | |
232 | name and location have changed. | |
233 | ||
234 | The reason for the change is to allow track name parsing to be | |
235 | centrally configured, rather than every interface to DisOrder having | |
236 | to implement it locally. | |
237 | ||
238 | If you do not install new namepart directives into the main | |
239 | configuration file then track titles will show up blank. | |
240 | ||
241 | If you do not remove the trackname-part directives from the web | |
242 | interface configuration then you will get error messages in the web | |
243 | server's error log. | |
244 | ||
245 | Local Variables: | |
246 | mode:outline | |
247 | fill-column:79 | |
248 | End: |