forked from expo/troggle
moving docm from README to handbook
This commit is contained in:
parent
bf5d0556fc
commit
3f6fb260a4
166
README.txt
166
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
|
||||
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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user