]> www.dxcluster.org Git - spider.git/blob - UPGRADE.mojo
show git branch on show/version
[spider.git] / UPGRADE.mojo
1 There are the notes for upgrading to the mojo branch.
2
3 There is NO POINT in doing this at the moment unless you are running a node with many (>50)
4 users. It is the future, but at the moment I am testing larger and larger installations to
5 check that it a) still works as people imagine it should and b) it provides the improvement
6 in scaling that I am anticipating. There are no significant new features - yet. 
7
8 The BIG TICKET ITEM in this branch is that (potentially) "long lived" commands such as sh/dx
9 and commands that poll external internet resources now don't halt the flow of data through
10 the node. I am also using a modern, event driven, web socket "manager" called Mojolicious
11 which is considerably more efficient than what went before (but is not necessary for small
12 nodes). There are some 200-400 user nodes out there that will definitely see the difference
13 in terms of both CPU usage and general responsiveness. Using Mojolicious also brings the
14 tantalising possibility of grafting on a web frontend, as it were, to the "side" of a
15 DXSpider node. But serious work on this won't start until we have a stable base to work
16 on. Apart from anything else there will, almost certainly, need to be some internal data
17 structure reorganisation before a decent web frontend could be constructed.
18
19 *IMPORTANT* There is an action needed to go from mojo build 228 and below. See items marked
20 *IMPORTANT* below. 
21
22 Upgrading is not for the faint of heart. There is no installation script (but there
23 will be) so, for the time being, you need to do some manual editing. Also, while there is
24 a backward path, it will involve moving various files from their new home (/spider/local_data),
25 back to where they came from (/spider/data).
26
27 Prerequisites:
28
29         A supply of good, strong tea - preferably in pint mugs. A tin hat, stout boots, a
30         rucksack with survival rations and a decent miners' lamp might also prove comforting. I
31         enclose this link: http://www.noswearing.com/dictionary in case you run out of swear words.
32
33         An installed and known working git based installation. Mojo is not supported under CVS or
34         installation from a tarball. 
35
36         perl 5.10.1, preferably 5.14.1 or greater. This basically means running ubuntu 12.04 or
37         later (or one of the other linux distros of similar age or later). The install instructions are
38         for debian based systems. IT WILL NOT WORK WITHOUT A "MODERN" PERL. Yes, you can use
39         bleadperl if you know how to use it and can get it to run the node under it as a daemon
40         without resorting the handy URL supplied above. Personally, I wouldn't bother. It's
41         easier and quicker just to upgrade your linux distro. Apart from anything else things like ssh
42         ntpd are broken on ALL older systems and will allow the ungodly in more easily than something
43         modern.
44
45 Install cpamminus:
46
47         sudo apt-get install cpanminus
48 or
49     wget -O - https://cpanmin.us | perl - --sudo App::cpanminus
50 or
51         sudo apt-get install curl
52         curl -L https://cpanmin.us | perl - --sudo App::cpanminus
53
54 You will need the following CPAN packages:
55
56         If you are on a Debian based system (Devuan, Ubuntu, Mint etc) that is reasonably new (I use Ubuntu
57         18.04 and Debian 10) then you can simply do:
58
59         sudo apt-get install libev-perl libmojolicious-perl libjson-perl libjson-xs-perl libdata-structure-util-perl
60
61     or on Redhat based systems you can install the very similarly (but not the same) named
62         packages. I don't the exact names but using anything less than Centos 7 is likely to cause
63         a world of pain. Also I doubt that EV and Mojolicious are packaged for Centos at all.
64
65         If in doubt or it is taking too long to find the packages you should build from CPAN. Note: you may
66         need to install the essential packages to build some of these. At the very least you will need
67         to install 'make' (sudo apt-get install make) or just get everything you are likely to need with:
68         
69         sudo apt-get install build-essential.
70
71         sudo cpanm EV Mojolicious JSON JSON::XS Data::Structure::Util
72         
73         # just in case it's missing
74         sudo apt-get install top
75
76 Please make sure that, if you insist on using operating system packages, that your Mojolicious is
77 at least version 7.26. Mojo::IOLoop::ForkCall is NOT LONGER IN USE! The current version at time
78 of writing is 8.36.
79
80 Login as the sysop user.
81
82 Edit your /spider/local/DXVars.pm so that the bottom of the file is changed from something like:
83
84 ---- old ----
85
86          # the port number of the cluster (just leave this, unless it REALLY matters to you)
87          $clusterport = 27754;
88
89          # your favorite way to say 'Yes'
90          $yes = 'Yes';
91
92          # your favorite way to say 'No'
93          $no = 'No';
94
95          # the interval between unsolicited prompts if not traffic
96          $user_interval = 11*60;
97
98          # data files live in 
99          $data = "$root/data";
100
101          # system files live in
102          $system = "$root/sys";
103
104          # command files live in
105          $cmd = "$root/cmd";
106
107          # local command files live in (and overide $cmd)
108          $localcmd = "$root/local_cmd";
109
110          # where the user data lives
111          $userfn = "$data/users";
112
113          # the "message of the day" file
114          $motd = "$data/motd";
115
116          # are we debugging ?
117          @debug = qw(chan state msg cron );
118
119 ---- to this: ----
120
121          # the port number of the cluster (just leave this, unless it REALLY matters to you)
122          $clusterport = 27754;
123
124          # your favorite way to say 'Yes'
125          $yes = 'Yes';
126
127          # your favorite way to say 'No'
128          $no = 'No';
129
130          # this is where the paths used to be which you have just removed
131          
132          # are we debugging ?
133          @debug = qw(chan state msg cron );
134
135 ---- new  ------
136
137 There may be other stuff after this in DXVars.pm, that doesn't matter. The point is to remove
138 all the path definitions in DXVars.pm. If this isn't clear to you then it would be better if
139 you asked on dxspider-support for help before attempting to go any further.
140
141 One of the things that will happen is that several files currently in /spider/data will be
142 placed in /spider/local_data. These include the user, qsl and usdb data files, the band and
143 prefix files, and various "bad" data files. I.e. everything that is modified from the base
144 git distribution. 
145
146 Now run the console program or telnet localhost and login as the sysop user.
147
148         export_users
149         bye
150
151 as the sysop user:
152
153    sudo service dxspider stop
154    or
155    sudo systemctl stop dxspider
156
157 having stopped the node:
158
159    mkdir /spider/local_data
160    git reset --hard
161    git pull
162    git checkout --track -b mojo origin/mojo
163
164 if you have not already done this:
165
166    sudo ln -s /spider/perl/console.pl /usr/local/bin/dx
167    sudo ln -s /spider/perl/*dbg /usr/local/bin
168
169 *IMPORTANT* (for any build of dxspider) regardless of branch below build 229 run:
170
171         /spider/perl/convert-users-v3-to-v4.pl
172         
173 Now in another window run:
174
175         watchdbg
176
177 and finally:
178
179    sudo service dxspider start
180    or
181    sudo service systemctl start dxspider
182
183 You should be aware that this code base is now under active development and, if you do a 'git pull',
184 what you get may be broken. But, if this does happen, the likelihood is that I am actively working
185 on the codebase and any brokenness may be fixed (maybe in minutes) with another 'git pull'.
186
187 I try very hard not to leave it in a broken state...
188
189 Dirk G1TLH
190
191
192
193