expo/troggle
2
0
Fork 1
mirror of https://expo.survex.com/repositories/troggle/.git synced 2024-11-21 23:01:52 +00:00
Code Issues 19 Projects 3 Activity

moving docm from README to handbook

Browse Source
This commit is contained in:
Philip Sargent 2021-10-29 22:18:36 +03:00
parent bf5d0556fc
commit 3f6fb260a4
1 changed files with 17 additions and 149 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

166
README.txt
View File

@ -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
2. install pip, django & patch django
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
1. set up the ssh key-exchange with the git server so you can clone troggle
http://expo.survex.com/handbook/computing/keyexchange.html
Setting up directories
----------------------
- create an 'expo' directory in which you also have the loser/, expoweb/ and drawings/ repositories
- git clone (see below) the current latest troggle from the 'python3' git branch into
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.
see http://expo.survex.com/handbook/troggle/troglaptop.html and
http://expo.survex.com/handbook/troggle/serverconfig.html
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.