]> dxcluster.org Git - spider.git/blob - UPGRADE.mojo
force git -C $root to make sure it gets its root
[spider.git] / UPGRADE.mojo
1 9th July 2020
2 -------------
3
4 There are the notes for upgrading to the mojo branch. PLEASE NOTE
5 THERE HAVE BEEN CHANGES FOR all MOJO BRANCH USERS. See APPENDIX(i) at
6 the end of this document.
7
8 There is NO POINT in doing this at the moment unless you are running a
9 node with many (>50) users. It is the future, but at the moment I am
10 testing larger and larger installations to check that it a) still
11 works as people imagine it should and b) it provides the improvement
12 in scaling that I am anticipating. There are no significant new
13 features - yet.
14
15 The BIG TICKET ITEM in this branch is that (potentially) "long lived"
16 commands such as sh/dx and commands that poll external internet
17 resources now don't halt the flow of data through the node. I am also
18 using a modern, event driven, web socket "manager" called Mojolicious
19 which is considerably more efficient than what went before (but is not
20 necessary for small nodes). There are some 200-400 user nodes out
21 there that will definitely see the difference in terms of both CPU
22 usage and general responsiveness. Using Mojolicious also brings the
23 tantalising possibility of grafting on a web frontend, as it were, to
24 the "side" of a DXSpider node. But serious work on this won't start
25 until we have a stable base to work on. Apart from anything else there
26 will, almost certainly, need to be some internal data structure
27 reorganisation before a decent web frontend could be constructed.
28
29 *IMPORTANT* There is an action needed to go from mojo build 228 and
30 *below. See items marked IMPORTANT* below.
31
32 Upgrading is not for the faint of heart. There is no installation
33 script (but there will be) so, for the time being, you need to do some
34 manual editing. Also, while there is a backward path, it will involve
35 moving various files from their new home (/spider/local_data), back to
36 where they came from (/spider/data).
37
38 Prerequisites:
39
40         A supply of good, strong tea - preferably in pint mugs. A tin hat,
41         stout boots, a rucksack with survival rations and a decent miners'
42         lamp might also prove comforting. I enclose this link:
43         http://www.noswearing.com/dictionary in case you run out of swear
44         words.
45
46         An installed and known working git based installation. Mojo is not
47         supported under CVS or installation from a tarball.
48
49         perl 5.10.1, preferably 5.14.1 or greater. This basically means
50         running ubuntu 12.04 or later (or one of the other linux distros
51         of similar age or later). The install instructions are for debian
52         based systems. IT WILL NOT WORK WITHOUT A "MODERN" PERL. Yes, you
53         can use bleadperl if you know how to use it and can get it to run
54         the node under it as a daemon without resorting the handy URL
55         supplied above. Personally, I wouldn't bother. It's easier and
56         quicker just to upgrade your linux distro. Apart from anything
57         else things like ssh ntpd are broken on ALL older systems and will
58         allow the ungodly in more easily than something modern.
59
60 Install cpamminus:
61
62         sudo apt-get install cpanminus
63 or
64     wget -O - https://cpanmin.us | perl - --sudo App::cpanminus
65 or
66         sudo apt-get install curl
67         curl -L https://cpanmin.us | perl - --sudo App::cpanminus
68
69 You will need the following CPAN packages:
70
71         If you are on a Debian based system (Devuan, Ubuntu, Mint etc)
72         that is reasonably new (I use Ubuntu 18.04 and Debian 10) then you
73         can simply do:
74
75         sudo apt-get install libev-perl libmojolicious-perl libjson-perl libjson-xs-perl libdata-structure-util-perl libmath-round-perl
76
77     or on Redhat based systems you can install the very similarly (but
78         not the same) named packages. I don't know the exact names but
79         using anything less than Centos 7 is likely to cause a world of
80         pain. Also I doubt that EV and Mojolicious are packaged for Centos
81         at all.
82
83         If in doubt or it is taking too long to find the packages you
84         should build from CPAN. Note: you may need to install the
85         essential packages to build some of these. At the very least you
86         will need to install 'make' (sudo apt-get install make) or just
87         get everything you are likely to need with:
88         
89         sudo apt-get install build-essential.
90
91         sudo cpanm EV Mojolicious JSON JSON::XS Data::Structure::Util Math::Round
92         
93         # just in case it's missing (top, that is)
94         sudo apt-get install procps
95
96 Please make sure that, if you insist on using operating system
97 packages, that your Mojolicious is at least version
98 7.26. Mojo::IOLoop::ForkCall is NOT LONGER IN USE! The current version
99 at time of writing is 8.36.
100
101 Login as the sysop user.
102
103 Edit your /spider/local/DXVars.pm so that the bottom of the file is
104 changed from something like:
105
106 ---- old ----
107
108          # the port number of the cluster (just leave this, unless it REALLY matters to you)
109          $clusterport = 27754;
110
111          # your favorite way to say 'Yes'
112          $yes = 'Yes';
113
114          # your favorite way to say 'No'
115          $no = 'No';
116
117          # the interval between unsolicited prompts if not traffic
118          $user_interval = 11*60;
119
120          # data files live in 
121          $data = "$root/data";
122
123          # system files live in
124          $system = "$root/sys";
125
126          # command files live in
127          $cmd = "$root/cmd";
128
129          # local command files live in (and overide $cmd)
130          $localcmd = "$root/local_cmd";
131
132          # where the user data lives
133          $userfn = "$data/users";
134
135          # the "message of the day" file
136          $motd = "$data/motd";
137
138          # are we debugging ?
139          @debug = qw(chan state msg cron );
140
141 ---- to this: ----
142
143          # the port number of the cluster (just leave this, unless it REALLY matters to you)
144          $clusterport = 27754;
145
146          # your favorite way to say 'Yes'
147          $yes = 'Yes';
148
149          # your favorite way to say 'No'
150          $no = 'No';
151
152          # this is where the paths used to be which you have just removed
153          
154          # are we debugging ?
155          @debug = qw(chan state msg cron );
156
157 ---- new  ------
158
159 There may be other stuff after this in DXVars.pm, that doesn't
160 matter. The point is to remove all the path definitions in
161 DXVars.pm. If this isn't clear to you then it would be better if you
162 asked on dxspider-support for help before attempting to go any
163 further.
164
165 One of the things that will happen is that several files currently in
166 /spider/data will be placed in /spider/local_data. These include the
167 user, qsl and usdb data files, the band and prefix files, and various
168 "bad" data files. I.e. everything that is modified from the base git
169 distribution.
170
171 Now run the console program or telnet localhost and login as the sysop
172 user.
173
174         export_users
175         bye
176
177 as the sysop user:
178
179    sudo service dxspider stop
180    or
181    sudo systemctl stop dxspider
182
183 having stopped the node:
184
185    mkdir /spider/local_data
186    git reset --hard
187    git pull --all
188    git checkout --track -b mojo origin/mojo
189
190 if you have not already done this:
191
192    sudo ln -s /spider/perl/console.pl /usr/local/bin/dx
193    sudo ln -s /spider/perl/*dbg /usr/local/bin
194
195 Now in another window run:
196
197         watchdbg
198
199 and finally:
200
201    sudo service dxspider start
202    or
203    sudo service systemctl start dxspider
204
205 You should be aware that this code base is now under active
206 development and, if you do a 'git pull', what you get may be
207 broken. But, if this does happen, the likelihood is that I am actively
208 working on the codebase and any brokenness may be fixed (maybe in
209 minutes) with another 'git pull'.
210
211 I try very hard not to leave it in a broken state...
212
213 Dirk G1TLH
214
215 APPENDIX(i)
216
217 Before shutting down to do the update, do a 'sh/ver' and take node of
218 the current git revision number (the hex string after "git: mojo/" and
219 the "[r]"). Also do an 'export_users' (belt and braces).
220
221 With this revision of the code, the users.v3 file will be replaced
222 with users.v3j.  On restarting the node, the users.v3j file will be
223 generated from the users.v3 file. The users.v3 file is not changed.
224 The process of generation will take up to 30 seconds depending on the
225 number of users in your file, the speed of your disk(s) and the CPU
226 speed (probably in that order. On my machine, it takes about 5
227 seconds, on an RPi??? This is a reversable change. Simply checkout the
228 revision you noted down before ("git checkout <reversion>") and email
229 me should anything go wrong.
230
231 Part of this process may clear out some old records or suggest that
232 there might errors. DO NOT BE ALARM. This is completely normal.
233
234 This change not only should make the rebuilding of the users file
235 (much) less likely, but tests suggest that access to the users file is
236 about 2.5 times quicker. How much difference this makes in practise
237 remains to be seen.
238
239 When you done this, in another shell, run
240 /spider/perl/create_dxsql.pl. This will convert the DXQSL system to
241 dxqsl.v1j (for the sh/dxqsl <call> command). When this is finished,
242 run 'load/dxqsl' in a console (or restart the node, but it isn't
243 necessary).
244
245 This has been done to remove Storable - completely - from active use
246 in DXSpider. I have started to get more reports of user file
247 corruptions in the last year than I ever saw in the previous 10. One
248 advantage of this is that change is that user file access is now 2.5
249 times faster. So things like 'export_users' should not stop the node
250 for anything like as long as the old version.
251
252 On the subject of export_users. Once you are happy with the stability
253 of the new version, you can clean out all your user_asc.* files (I'd
254 keep the 'user_asc' that you just created for emergencies). The modern
255 equivalent of this file is now called 'user_json' and can used in
256 exactly the same way as 'user_asc' to restore the users.v3j file (stop
257 the node; cd /spider/local_data; perl user_json; start the node).
258
259