moving docm from README to handbook

README.txt

@@ -9,9 +9,15 @@ and was used for Erebus caves. The CUCC variant uses files as the definitive dat
 not the database and lives at http://expo.survex.com/repositories/troggle/.git/
 
 For the server setup, see /_deploy/debian/wookey-exposerver-recipe.txt
+and see http://expo.survex.com/handbook/troggle/serverconfig.html
+
+Much material which was in this file has been moved to 
+http://expo.survex.com/handbook/troggle/serverconfig.html
 
 See copyright notices in
 http://expo.survex.com/handbook/computing/contribute.html
+and for context see
+http://expo.survex.com/handbook/computing/onlinesystems.html 
 
 Troggle setup
 =============
@@ -20,36 +26,13 @@ Troggle setup
    http://expo.survex.com/handbook/troggle/serverconfig.html
    http://expo.survex.com/handbook/troggle/trogdangoup.html
    and at troggle/debian/serversetup 
-1. git clone troggle into correct directory structure
+1. set up the ssh key-exchange with the git server so you can clone troggle
-2. install pip, django & patch django
+   http://expo.survex.com/handbook/computing/keyexchange.html
-3. configure django to recognise troggle 
-4. configure django to be able to find expofiles etc.
-
-See http://expo.survex.com/handbook/computing/onlinesystems.html 
 
 Setting up directories
 ----------------------
-- create an 'expo' directory in which you also have the loser/, expoweb/ and drawings/ repositories
+see  http://expo.survex.com/handbook/troggle/troglaptop.html and 
-- git clone (see below) the current latest troggle from the 'python3' git branch into 
+http://expo.survex.com/handbook/troggle/serverconfig.html
-  a folder called 'troggle'
-- all the 4 repos should now be siblings, and also siblings with expofiles/ and expowebcache/
-- if you have those repos elsewhere, set up symlinks in the directory above troggle
-  so that troggle thinks they are siblings
-full details and example script code is at  http://expo.survex.com/handbook/troggle/troglaptop.html
-
-Troggle itself
--------------
-Choose the directory where you will keep troggle, (which must be named "troggle")
-and git clone troggle into it using the following command:
-
-git clone git://expo.survex.com/troggle
-or more reliably
-git clone ssh://expo@expo.survex.com/home/expo/troggle
-but you will have to set up the ssh key-exchange with the server to make that work.
-Key-exchange instructions: http://expo.survex.com/handbook/computing/keyexchange.html
-
-If you want to work on the source code and be able to commit, your account will need to be 
-added to the troggle project members list. Contact wookey  at wookware dot org to get this set up.
 
 Next, you need to fill in your local settings. Copy _deploy/WSL/localsettingsWSL.py 
 to a new file called localsettings.py and edit it and settings.py to match
@@ -70,6 +53,7 @@ We are now using Django 2.2.19
 We are installing with python3.7
 
 Install Django using pip, not with apt, on your test system.
+Conventionally on our main master expo server we install everything that we can as debian packages, not using pip.
 
 [installation instructions removed - now in http://expo.survex.com/handbook/troggle/troglaptop.html ]
 
@@ -78,65 +62,24 @@ Install Django using pip, not with apt, on your test system.
 
 Testing the django installation
 -------------------------------
-Test things by running these commands:
-$ django-admin --version
-$ django-admin 
-It should show a list of commands and complain:
-"..only Django core commands are listed as settings are not properly configured" 
 
-If you get an error when running
-$ django-admin
-Then run django-admin like this:
-python /usr/local/lib/python3.8/dist-packages/django/bin/django-admin.py
-which should fix the paths. From now on you should be able to run 
-$ django-admin 
-from within any folder on your machine.
 
-Now do
-$ cd troggle
-$ python manage.py
-
-You will get this error if everything is OK:  (error: No module named 'localsettings')
 So now rename one of the relevant platform files, e.g. if you are on WSL on Windows:
 $ mv localsettingsWSl.py localsettings.py
 
-The git repo copies have got munged passwords.
-So use sFTP to download the copies from expo.survex.com
 
 otherwise, if you are on debian:
 $ cp _deploy/debian/localsettings.py .
 
+The git repo copies have got munged passwords.
+localsettings.py is not stored in git, but does have the correct passwords.
+So use sFTP to download localsettings.py from expo.survex.com
+
 WARNING: only the WSL and debian variants are current in May 2021. All the others are so old that 
 they will need serious work to be useable. Copy what you need from WSL and debian variants of
 localsettings.py
 
-Now try this again:
-$ python manage.py
 
-and in additon to the [django] command list, you will now gets command lsists for [auth],
-[contenttypes], [core], and [sessions]. These are the modules (plugins) loaaded into django. 
-[core] is the core of troggle (but not all of it: the input file parsers are not in [core]).
-
-$ python manage.py check -v 3 --traceback
-
-Ideally this will list settings imports and then say
-System check identified no issues (0 silenced).
-
-If you get an error your python sys.path is probably not set correctly yet. Do
-$ python -m site
-when you are in your troggle directory to see the list of paths python looks 
-for when it is searching for packages (both django and troggle). 
-Ensure that the path to the troggle/ directory is in the list.
-It should be at the top, which is where the current working directory is.
-
-Now:
-python  manage.py check -v 3 --deploy
-which will give security warnings for deployment. Various middleware settings and 
-a warning not to use DEBUG=true in deployment. We always have DEBUG=True set for troggle
-as otherwise the users get useless error messages.
-
-python -Wall manage.py check 
-Gives warnings of deprecated Django which should be fixed asap.
 
 Now you need to edit the following settings in your localsettings.py file to match your
 development machine:
@@ -155,70 +98,12 @@ and then the FILES and EXPOFILES setings will be ignored.
 
 You will probably want to change the various EMAIL settings too.
 
-Now do
-python  manage.py test -v 2
-Runs our test suite.
 
-If you get an error, and you probably will, have a look in the test file, e.g. for this error:
-FAIL: test_page_folk (troggle.core.TESTS.tests.PageTests) 
-look in the file      troggle/code/TESTS/tests.py in the class PageTests.
-It will also say:
-  File "/mnt/c/EXPO/troggle/core/TESTS/tests.py", line 266, in test_page_folk
-which means that the asssert failure in on line 266 of troggle/code/TESTS/tests.py
-and that the failure function is test_page_folk()
-If you look at this you will see that line 264 is:
-        response = self.client.get('/folk/index.htm')
 
-so this file is missing. Duh. Of course it is. We downloaded troggle from git but we didn't run
-the standalone script to generate the folk list. It is top of the list in
-http://expo.survex.com/handbook/troggle/scriptscurrent.html#folk
 
-So do this:
-cd ../expoweb/folk
-python ../scripts/make-folklist.py <folk.csv >index.htm
-cd ../../troggle
-
-Or just sFTP a copy from expo.survex.com
-
-and run the tests again:
-
-python  manage.py test -v 2
-
-Yeah if you were paying attention, you will see that this has done a git commit for a test file
-in the drawings repo locally.
-Sorry about that. the test harness does not yet undo that. So you will need ot manually reverse that commit: go into your favourite git tool. In VS code the command is Commit: Undo last commit
 
 If yo have run the test suite several times you will need to undo several commits (and delete the files producd by the test suite).
 
-Registering troggle as a django application
--------------------------------------------
-In your troggle directory run
-$ django-admin 
-and check you got the same output as before.
-
-Then try 
-$ python manage.py
-It may not work. But if it does it will
-now show a superset of the previous output: the [django] commands
-available but also other options. Run
-$ python manage.py check
-$ python manage.py diffsettings
-This last one shows everything set in global settings, settings and localsettings.
-Anything different from global settings  (django built-in) has '###' appended.
-
-$ python manage.py test -v 2
-Tests that it can create a database from all the model files.
-
-$ python manage.py migrate
-Tests the uptodateness of your sqlite database.
-$ python manage.py help migrate
-explains what this does and gives extra command line options.
-
-If you got an error traceback with
-$ python manage.py
-then the settings registration of troggle with django is incomplete.
-Delete all your cached .pyc files and try again.
-You probably have a mistake in your settings.py or localsettings.py files.
 
 CSS and media files
 -------------------
@@ -302,24 +187,6 @@ the expocvs group is used for git & hg
 
 all the users should bve in this group
 
-Running a Troggle server
-------------------------
-For high volume use, Troggle should be run using a web server like apache. 
-However, a quick way to get started is to use the development server built into Django. 
-This is limited though: directory redirection needs apache.
-
-To do this, run 
-$ python manage.py runserver 8000 -v 3
-from the troggle directory. This runs it on port 8000 so you see the website
-at http://localhost:8000/
-
-gunicorn also works. This runs with 9 workers (suitable for a 4-core processor):
-$ gunicorn --reload -w 9 -b :8000 wsgi
-
-EXTRAS
-------
-cgit - https://git.zx2c4.com/cgit/about/
-search - https://www.ibm.com/developerworks/opensource/library/os-xapianomega/index.html
 
 Running a Troggle server with Apache
 ------------------------------------
@@ -351,7 +218,7 @@ Alias       /expofiles    /home/expo/expofiles
 Alias       /static/      /home/expo/static/
 
 
-Unlike the "runserver" method, apache requires a restart before it will use
+Unlike the django "manage.py runserver" method, apache requires a restart before it will use
 any changed files:
 
 sudo service apache2 restart
@@ -363,6 +230,7 @@ olly: ExecStart=/usr/sbin/apachectl start
 olly: ExecStop=/usr/sbin/apachectl stop
 olly: ExecReload=/usr/sbin/apachectl graceful
 
+
 Experimental additions
 ----------------------
 These are untried tools which help us document how troggle works.