README for Logiweb distribution Klaus Grue, 2007 Prerequisites Logiweb is available under the GNU GPL. Installation requires Linux, clisp 2.41 (I also run it on 2.39), latex, bibtex, makeindex, dvipdfm, and an Apache web server. Clisp is available from http://clisp.cons.org/. Logiweb has been tested on Fedora. Standard first time installation: 01> Download logiweb-.tar.gz 02> tar zxf logiweb-.tar 03> cd logiweb- 04> edit ./logiweb.conf (logiweb.conf tells which parameters you *must* supply) 05> make 06> su 07> create a user named 'logiweb' 08> make install Optionally (if you want to run the testsuite): 09> su yourself 10> make test For trouble shooting see the "Trouble shooting" section later. Post installation, each user: Each user should create a 'publication directory' such as /var/www/html/MYNAME for publication of Logiweb pages. Each user should also create a file .logiweb/logiweb.conf in the users home directory containing something like this: url = http://www.my.domain/MYNAME cache = /home/MYNAME/cache desttemp = $PAGE$/undated destsubmit= $PAGE$/$DATE$ The url must point to the publication directory. Without a cache, the pyk compiler has to retranslate each referenced page at every compilation which takes a lot of time. With the cache, the pyk compiler stores translated pages in the cache so that each referenced page only has to be translated once. The user may freely delete the cache or delete arbitrary files in the cache. The desttemp and destsubmit options state where unsubmitted and submittet pages, respectively, are placed in the publication directory. Post installation, the administrator: If a logiwiki was installed, the administrator may run the tutorial to see that everything works. Also see the section 'Ways of testing that logiweb is properly installed' later in this file. Reinstallation: If your site configuration file is in /etc/logiweb/logiweb.conf then do a standard installation, but omit steps 04 and 07. Then the parameters in your site configuration file are used. The reinstallation sequence then becomes: 01> Download logiweb-.tar.gz 02> tar zxf logiweb-.tar 03> cd logiweb- 05> make 06> su 08> make install If your site configuration file is in /foo/bar/my.conf then in step 04 change varconf=/etc/logiweb/logiweb.conf to varconf=/foo/bar/my.conf in ./logiweb.conf. The reinstallation sequence then becomes: 01> Download logiweb-.tar.gz 02> tar zxf logiweb-.tar 03> cd logiweb- 04> Set varconf=/foo/bar/my.conf in ./logiweb.conf. 05> make 06> su 08> make install To make a fresh install, delete your site configuration file first. Then ./logiweb.conf will be used. But it is probably wiser to edit your site configuration file to contain what you need. If you reinstall often, and your site configuration file is not in /etc/logiweb/logiweb.conf, consider setting varconf in ~/.logiweb/logiweb.conf or use the LGWVARCONF environment variable. Uninstallation: Run 'pyk -- -uninstall' (c.f. 'man pyk'). Alternatively, if you still have the source tree, do 'make uninstall'. Redistribution: Run 'make dist' Making a new distribution if base, check, etc. in doc/page and the html version in doc/man are up to date. > make newdist > edit CHANGELOG > make dist Making a new distribution if base, check, and Peano should be re-rendered and the manual pages re-translated > make manual > make > make newdist > edit CHANGELOG > make dist Making a new distribution if base, check, and Peano should be recompiled: > make manual > make most > make newpages > make newdist > edit CHANGELOG > make dist Make targets: make = make all make code = compile everything make enhancement = pre-load standard pages into pyk compiler make most = make code + make enhancement make all = make code + re-render pages + make enhancement make newpages = re-compile pages (old timestamps are lost forever) make clean = clean up after make most make distclean = clean up after make all make manual = translate man pages to html using rman make maintainerclean = clean up after make all + make manual make install = install everything make uninstall = remove installation make dist = make distclean + make distribution tar-ball make newdist = set version number make test = run test suite (Logiweb must be installed first) Run 'make manual' whenever the man pages have been changed. One can only use 'make manual' on systems with 'rman' installed. Ways of testing that logiweb is properly installed: Issue 'which logiweb' 'which pyk' 'which lgwping' 'which lgwrelay' to see that those programs are installed. Issue Issue 'man logiweb' 'man pyk' 'man lgwping' 'man lgwrelay' to see that the man pages are installed. Issue Issue 'logiweb -- -version' 'logiweb -- -help' 'logiweb -- -option' 'pyk -- -version' 'pyk -- -help' 'pyk -- -option' 'lgwping -v 'lgwrelay' to see that the programs can run. The response from 'lgwrelay' should be Content-type: text/plain ... usage: ... Issue 'ps -C logiweb' to get something like PID TTY TIME CMD 6079 ? 00:00:00 logiweb The question mark under TTY shows that the Logiweb server runs as a demon. This is the server that was started during 'make install'. Issue 'lgwping' to ping the Logiweb server. Expect to get something like lgwping 65535 127.0.0.1 02 result: 03CCEFE7E9F7E5E201BE91EEA0A6D39A0806 The result should start with 03CCEFE7E9F7E5E201 (the rest is a timestamp so it changes with time:-) The '02' is the code of a Logiweb 'ping'. In a browser, look up http://your.domain/logiweb to see the home page of your new Logiweb installation. Click on 'Logiweb Server' to get a page with headline User interface for the Logiweb server at udp/your.domain/65535 Issue 'make test' if you have plenty of time. Troubleshooting In case you run into problems, go to http://logiweb.eu/ and read the logiweb@diku.dk mailing list archives. If that does not help, subscribe to logiweb@diku.dk and then post your question there. When you do so, make sure you include a copy of what you did (a copy from your shell window showing the commands you issued and the response you got). Also include the output from the following command: > clisp --version Also include your logiweb.conf file. The logiweb.conf file typically resides in /etc/logiweb/logiweb.conf. But if there is no file there then include the logiweb.conf file from the root of the source tree. If you have managed to install logiweb but has trouble with pyk then also include the output from the following commands: > pyk -- -option > pyk -- -version If you have trouble with the server (the program actually named 'logiweb') then also include the latest log file from the server (typically located in /var/log/logiweb/). Also include the output from the following commands: > server -- -option > server -- -version Roadmap In standard installation: /usr/local/bin/logiweb: The Logiweb server /usr/local/bin/pyk: Pyk compiler for generating Logiweb pages /usr/local/bin/lgwping: Program for pinging Logiweb servers /usr/local/bin/lgwrelay: Program used by the Logiweb relay script /usr/local/lib/logiweb.so: Shared object used by the Logiweb server /etc/rc.d/init.d/logiweb: Script that starts the Logiweb server /var/www/logiweb/relay: The Logiweb relay script (a CGI-script) /etc/httpd/conf.d/logiweb.conf: Configuration script for Apache server /var/log/logiweb/*: Output from Logiweb server /var/run/logiweb.pid: Process ID of Logiweb server /var/lock/subsys/logiweb: Lock set by Logiweb server /var/www/html/logiweb: Html pages of Logiweb installation Useful commands: /sbin/service logiweb start: Start Logiweb server /sbin/service logiweb stop: Stop Logiweb server /sbin/service logiweb restart: Restart Logiweb server /sbin/service logiweb status: Ask if Logiweb server runs /sbin/chkconfig logiweb reset: Make the Logiweb server start at next boot /sbin/chkconfig --del logiweb: Avoid starting the Logiweb server at next boot