mirror of
https://expo.survex.com/repositories/expoweb/.git/
synced 2024-11-22 07:11:55 +00:00
Moving docm to right place from the server README
This commit is contained in:
parent
5a6d1934e5
commit
bd64c9cd47
@ -52,29 +52,55 @@ expoweb (repo)
|
||||
|
||||
<p>The handbook illustrates the i/t/l idiom whereby an image file (i) is displayed with a paragraph of text as an HTML file (l) and there is a thumbnail image (t) which is included in another document, e.g. see <a href="../../1623/walkin.htm">the photographic guide to the walk from the toll road car park</a>.
|
||||
|
||||
<h4 id="js">CSS and JavaScript</a></h3>
|
||||
<h4 id="css">CSS and HTML</a></h4>
|
||||
|
||||
<p>The <var>expoweb</var> repo contains all the HTML files and basic CSS files. The <var>troggle</var> repo contains the HTML templates, CSS and some javscript for the troggle report pages generated dynamically. There are also javascript packages installed directly on the operating system which are used by some <var>expoweb</var> pages: <var>CaveScript</var> for showing 3D views of cave centreline data, <var>CodeMirror</var> for syntax-colouring survex files and <var>openlayers</var> for geographic mapping integration. These javascript packages are only documented in the configuration instructions, see below.
|
||||
<p>The <var>expoweb</var> repo contains all the HTML files and basic CSS files. The <var>troggle</var> repo contains the HTML templates, CSS for the troggle report pages generated dynamically and a copy of the CSS, thumbnail images and javascript for the Django admin package which has to be available under the url '/site_media/' (which resolves to expo/troggle/media/) for the admin system to work.
|
||||
<p>
|
||||
See the live report on which urls resolve to which actual folders at <a href="/pathsreport">pathsreport</a>.
|
||||
|
||||
<h4 id="js">Javascript</a></h4>
|
||||
There are javascript packages installed directly on the operating system on the server, i.e. in<br>
|
||||
<code>/usr/share/javascript</code>
|
||||
which are used by some <var>expoweb</var> pages:
|
||||
<ul>
|
||||
<li><var>CaveScript</var> for showing 3D views of cave centreline data,
|
||||
<li><var>CodeMirror</var> for syntax-colouring survex files
|
||||
<li><var>openlayers</var> for geographic mapping integration, for out slippy map showing paths and entrances at <a href="/map/map.html">/map/map.html</a>
|
||||
<li><var>leaflets</var> and experimental mapping test (only on /map/index-leaflet.html )
|
||||
</ul>
|
||||
These javascript packages are not documented but some are mentioned in <a href="troglaptop.html">the soft dev laptop</a> configuration.
|
||||
|
||||
<p>Currently installed on the server (October 2021) are the following javascript packages which are <em>not used at all by troggle or any of the expo website</em>:
|
||||
<ul>
|
||||
<li>jquery
|
||||
<li>jquery-ui
|
||||
<li>mootools
|
||||
<li>sphinxdoc
|
||||
<li>underscore
|
||||
</ul>
|
||||
<p>Presumably these are used by something else hosted on the server ? Anyway, if you are setting up a new troggle sever you don't need them.
|
||||
|
||||
<h3 id="what">Server configuration: software</a></h3>
|
||||
|
||||
<ul>
|
||||
<li>apache webserver *
|
||||
<li>MySQL/MariaDB database *
|
||||
<li>packaged javascript *
|
||||
<li>expofiles *
|
||||
<li>cgit (live webpage showing git status of repos)
|
||||
<li>MySQL/MariaDB database *
|
||||
<li>packaged javascript
|
||||
<li>cgit (live webpage showing git status of repos) - <a href="https://git.zx2c4.com/cgit/about/">qit.zx2c4.com/cgit</a>
|
||||
<li>Makefile (obsolete?)
|
||||
<li>bins
|
||||
<li>bins (used to regenerate the photo albums)
|
||||
<li>cron
|
||||
<li>xapian (search function)
|
||||
<li>boe
|
||||
<li>xapian (search function) - <a href="https://xapian.org/">xapian.org</a>. Wookey did this in 2020.
|
||||
|
||||
<li>boe (bank of expo - not troggle)
|
||||
</ul>
|
||||
* These are essential to make troggle work at all.
|
||||
|
||||
<p>The server configuration scripts are in <var>troggle/debian/serversetup</var> and are also
|
||||
<p>The server configuration scripts are in the file <var>troggle/debian/serversetup</var> and are also
|
||||
documented with notes in <var>troggle/README.txt</var>. It is intended that the full documentation will
|
||||
be copied here in due course and that fully automated server setup scripts will be developed
|
||||
be copied here in due course.
|
||||
<p>It is hoped that we will develop fully automated server setup scripts (such as are used by CUYC for their Django system)
|
||||
<ul>
|
||||
<li>to create a development server running locally on a personal machine
|
||||
<li>to install the master system following a new operating system install on the public server
|
||||
@ -311,7 +337,6 @@ expofiles
|
||||
│ ├── training-info
|
||||
│ ├── uploads
|
||||
│ └── wiki
|
||||
├── unidentified_scripts
|
||||
├── uploads
|
||||
├── video
|
||||
│ ├── 2004
|
||||
@ -361,10 +386,27 @@ connected with an apache configuration
|
||||
<code>ScriptAlias /search /usr/lib/cgi-bin/omega/omega</code> in <var>~expo/config/apache/expo.conf</var>.
|
||||
Installed by Wookey in May 2020.
|
||||
|
||||
<h3>Running a test Troggle server</h3>
|
||||
<p>
|
||||
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 so CodeMirror and CaveView won't work as the url /javascript/ will not exist.
|
||||
<p>
|
||||
To do this, run
|
||||
<code>
|
||||
$ python manage.py runserver 8000 -v 3
|
||||
</code>
|
||||
from the troggle directory. This runs it on port 8000 so you see the website
|
||||
at http://localhost:8000/
|
||||
<p>
|
||||
gunicorn also works. This runs with 9 workers (suitable for a 4-core processor,
|
||||
-w takes n+1 where n is the number of cores of your processor):
|
||||
<code>
|
||||
$ gunicorn --reload -w 9 -b :8000 wsgi
|
||||
</code>
|
||||
|
||||
<h3>boe</h3>
|
||||
<p>This is a perl script, and server by the webserver using the configuraiotn
|
||||
<code><pre>
|
||||
#bank of expo
|
||||
<p>This is a perl script, and served by the webserver using the url apache configuration<code><pre>#bank of expo
|
||||
#current expedition
|
||||
ScriptAlias /boe /home/expo/boe/boc/boc.pl
|
||||
<Directory /home/expo/boe/boc>
|
||||
@ -372,8 +414,7 @@ ScriptAlias /boe /home/expo/boe/boc/boc.pl
|
||||
SetHandler cgi-script
|
||||
Options +ExecCGI
|
||||
Require all granted
|
||||
</Directory></pre>
|
||||
</code> in <var>~expo/config/apache/expo.conf</var>.
|
||||
</Directory></pre></code> in <var>~expo/config/apache/expo.conf</var>.
|
||||
|
||||
<hr />
|
||||
Return to: <a href="trogdesign.html">Troggle design and future implementations</a><br />
|
||||
|
||||
@ -148,7 +148,7 @@ where it describes upgrading and testing with later versions of Django.
|
||||
<p>Follow this link to <a href="../computing/keyexchange.html">register a key with the expo server</a> to get git access if you have not already cloned the <var>:troggle:</var> repo.
|
||||
|
||||
<h4>git clone troggle</h4>
|
||||
<p>This creates a folder /troggle/ containing all the troggle code. </p>
|
||||
<p>You will do a git clone to create a folder /troggle/ containing all the troggle code. You need to clone the 'python-3' branch, if you an see multiple branches.</p>
|
||||
|
||||
<pre><code>cd ~
|
||||
cd ../expo
|
||||
@ -168,26 +168,119 @@ sudo ln -s /mnt/c/EXPO/expowebcache expowebcache</code></pre>
|
||||
<pre><code>git config --global user.email "you@example.com"
|
||||
git config --global user.name "Your Name"</code></pre>
|
||||
|
||||
<h4>do the basic health checks</h4>
|
||||
<h4>do the basic Django health checks</h4>
|
||||
<p>This all checks that the installation has completed properly.
|
||||
<pre><code>django-admin
|
||||
python manage.py
|
||||
python manage.py check -v 3 --traceback</code></pre>
|
||||
<pre><code>django-admin</code></pre>
|
||||
<p>The first line <var>django-admin</var> will complain that it has not got a SETTINGS file, but that's fine.
|
||||
See <a href="djangostart.html">django-admin initial output</a> for what you should expect to see at this point.
|
||||
If it crashes though, you have not managed to install the software completely.
|
||||
<p>The most important is the <var>python manage.py check</var>. If this works, then you have installed the software correctly. Now we test whether troggle is configured correctly:
|
||||
If you get an error when running
|
||||
<pre><code>django-admin</code></pre>
|
||||
Then run django-admin like this (using the python version you have installed in the folder underneath /lib/):
|
||||
<pre><code>python /usr/local/lib/python3.8/dist-packages/django/bin/django-admin.py</code></pre>
|
||||
which should fix the paths, but this means that you installed Django directly on your machine and not in a venv. From now on you should be able to run <var>django-admin </var>
|
||||
from within any folder on your machine.
|
||||
<p>Now try
|
||||
<pre><code>django-admin --version</code></pre>
|
||||
|
||||
The version number is the version of Django you have installed. Double check that it is the one you meant to install and check with <a href="trogdjangup.html">our Django versions page</a>.
|
||||
|
||||
<pre><code>python manage.py test -v 3 --traceback</code></pre>
|
||||
<p>This will run the entire troggle test suite of over 70 tests (it takes only a few seconds). It will probably have a dozen or so failures which will probably be because it can't find the various bits of the rest of the website. So the next task is to edit the SETTINGS files to match your machine and folder structure. So find the appropriate copy of the localsettings in /_deploy/ and copy it into the main troggle folder:
|
||||
<h4>do the basic troggle health checks</h4>
|
||||
<p>Now try
|
||||
<pre><code>python manage.py/code></code></pre>
|
||||
|
||||
You will get an error: No module named 'localsettings'. Fixing this is described below, but for now try:
|
||||
|
||||
<pre><code>python manage.py check -v 3 --traceback</code></pre><p>The most important is the <var>python manage.py check</var>. If this works, then you have installed the software correctly.
|
||||
<p>
|
||||
The next task is to edit the SETTINGS files to match your machine and folder structure. So find the appropriate copy of the localsettings in /_deploy/ and copy it into the main troggle folder:
|
||||
<pre><code>cp _deploy/wsl/localsettingsWSL.py localsettings.py</code></pre>
|
||||
<p>Now edit it and insert useful values for EXPOUSERPASS [e.g. cavey:beery], EXPOADMINUSERPASS [e.g. beery:cavey], SECRET_KEY and make sure that LIBDIR refers to the actual version of python you are using (sorry, this should be automatic).
|
||||
<p>Check that FILES and EXPOFILES are set to wherever you have put /expofiles/ or set 'EXPOFILESREMOTE = False' which will use expofiles on expo.survex.com instead.
|
||||
<p>Set <a href="https://docs.djangoproject.com/en/3.2/topics/email/#s-configuring-email-for-development">EMAIL_HOST and EMAIL_HOST_PASSWORD</a> to an email account you control that can send email. Then troggle can email you when some things go wrong. This may mean having to set EMAIL_PORT and MAIL_USE_TLS too (this is not used in troggle currently). Set EXPOUSER_EMAIL and EXPOADMINUSER_EMAIL to your own email address while you are doing software development. All these will be different when troggle is deployed on the public server.
|
||||
|
||||
<p>
|
||||
Now try this again:
|
||||
<pre><code>python manage.py</code></pre>
|
||||
|
||||
and in additon to the [django] command list, you will now gets command lists 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]).
|
||||
|
||||
<pre><code>python manage.py check -v 3 --traceback</code></pre>
|
||||
|
||||
Ideally this will list settings imports and then say<br>
|
||||
<var>System check identified no issues (0 silenced)</var>.
|
||||
<p>
|
||||
If you get an error your python sys.path is probably not set correctly yet. Do
|
||||
<pre><code>python -m site</code></pre>
|
||||
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). <br>
|
||||
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.
|
||||
<p>
|
||||
Now:
|
||||
<pre><code>python manage.py check -v 3 --deploy</code></pre>
|
||||
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.
|
||||
|
||||
<pre><code>python -Wall manage.py check </code></pre>
|
||||
Gives warnings of deprecated Django which should be fixed. You should not get any on a fresh install but youwill see this message when you are trying to upgrade troggle to use later versions of Django.
|
||||
|
||||
If you got an error traceback with
|
||||
<pre><code>python manage.py</code></pre>
|
||||
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.
|
||||
|
||||
<pre><code>python manage.py diffsettings</code></pre>
|
||||
This last one shows everything set in global settings, settings and localsettings.
|
||||
Anything different from global settings (django built-in) has '###' appended.
|
||||
|
||||
<pre><code>python manage.py help migrate
|
||||
python manage.py migrate</code></pre>
|
||||
Tests the uptodateness of your sqlite database. The help option
|
||||
explains what this does and gives extra command line options.
|
||||
|
||||
<h4>check full functionality</h4>
|
||||
<p>The test suite hardly skims the surface of what troggle does. You need to manually test all these too:
|
||||
|
||||
<p>Now run the test suite:
|
||||
|
||||
<pre><code>python manage.py test -v 3 --traceback</code></pre>
|
||||
<p>This will run the entire troggle test suite of over 70 tests (it takes only a few seconds).</code></pre>
|
||||
|
||||
<pre>
|
||||
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
|
||||
</pre>
|
||||
<p>The test suite has over 70 tests but does not cover all of what troggle does and does not use any real data. You need to manually test these too, after you have done a full data import:
|
||||
<br>- <var><a href="http://localhost:8000/pathsreport">http://localhost:8000/pathsreport</a></var>
|
||||
<br>- <var><a href="http://localhost:8000/stats">http://localhost:8000/stats</a></var>
|
||||
<br>- <var><a href="http://localhost:8000/people">http://localhost:8000/people</a></var> (takes a minute or so)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user