forked from expo/troggle
240 lines
8.1 KiB
Plaintext
240 lines
8.1 KiB
Plaintext
Updated 23 October 2021
|
|
|
|
Troggle is an application for caving expedition data management,
|
|
originally created for use on Cambridge University Caving Club (CUCC)expeditions
|
|
and licensed under the GNU Lesser General Public License.
|
|
|
|
Troggle has been forked into two projects. The original one is maintained by Aaron Curtis
|
|
and was used for Erebus caves. The CUCC variant uses files as the definitive data,
|
|
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
|
|
=============
|
|
0. read the very extensive online documentation and stop reading this README.
|
|
http://expo.survex.com/handbook/troggle/troglaptop.html
|
|
http://expo.survex.com/handbook/troggle/serverconfig.html
|
|
http://expo.survex.com/handbook/troggle/trogdangoup.html
|
|
and at troggle/debian/serversetup
|
|
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
|
|
----------------------
|
|
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
|
|
your machine's file locations.
|
|
Follow the instructions contained in the file to fill out your settings.
|
|
|
|
{ in _deploy/old/ we have these which are all very out of date:
|
|
localsettings-expo-live.py is the python2.7 settings for the server.
|
|
localsettingsubuntu.py
|
|
localsettingsdocker.py
|
|
localsettingswindows.py
|
|
localsettingspotatohut.py
|
|
}
|
|
|
|
Python3, Django, and Database setup
|
|
-----------------------------------
|
|
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 ]
|
|
|
|
[venv description removed - read it in http://expo.survex.com/handbook/troggle/troglaptop.html ]
|
|
|
|
|
|
Testing the django installation
|
|
-------------------------------
|
|
|
|
|
|
So now rename one of the relevant platform files, e.g. if you are on WSL on Windows:
|
|
$ mv localsettingsWSl.py localsettings.py
|
|
|
|
|
|
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 you need to edit the following settings in your localsettings.py file to match your
|
|
development machine:
|
|
|
|
FILES = Path('/mnt/f/expofiles/')
|
|
EXPOFILES = Path('/mnt/f/expofiles/')
|
|
|
|
All the other settings (drawings, expoweb etc.) will work fine if they are parallel directories
|
|
to the directory you installed troggle into. The troggle code can find out itself where it
|
|
is living.
|
|
|
|
If you do not have a local copy of /expofiles/ (40 GB), you can use the expo server copy if
|
|
you set:
|
|
EXPOFILESREMOTE = TRUE
|
|
and then the FILES and EXPOFILES setings will be ignored.
|
|
|
|
You will probably want to change the various EMAIL settings too.
|
|
|
|
|
|
|
|
|
|
|
|
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).
|
|
|
|
|
|
CSS and media files
|
|
-------------------
|
|
Temporarily we are not using the STATICFILES capability but are instead
|
|
serving css files from troggle/media/.. (see urls.py) using
|
|
view_surveys.cssfilessingle
|
|
i.e.
|
|
cssfilessingle() in core/view_surveys.py
|
|
|
|
Setting up survex
|
|
-----------------
|
|
You need to have survex installed as the command line tools 'cavern' is
|
|
used as part of the survex import process.
|
|
$ sudo apt install survex
|
|
|
|
Setting up tables and importing survey data
|
|
-------------------------------------------
|
|
Run
|
|
$ sudo python databaseReset.py
|
|
from the troggle directory will give you instructions.
|
|
|
|
[ NB Adding a new year/expedition requires adding a column to the
|
|
folk/folk.csv table - a year doesn't exist until that is done.]
|
|
|
|
Database
|
|
--------
|
|
If you want to use MySQL or Postgresql, download and install them.
|
|
However, you can also use Django with sqlite3
|
|
|
|
MariaDB database
|
|
----------------
|
|
Start it up with
|
|
$ sudo mysql -u -p
|
|
when it will prompt you to type in the password. Get this by reading the settings.py file in use on the server.
|
|
then
|
|
> CREATE DATABASE troggle;
|
|
> use troggle;
|
|
> exit;
|
|
|
|
Note the semicolons.
|
|
|
|
You can check the status of the db service:
|
|
$ sudo systemctl status mysql
|
|
|
|
You can start and stop the db service with
|
|
$ sudo systemctl restart mysql.service
|
|
$ sudo systemctl stop mysql.service
|
|
$ sudo systemctl start mysql.service
|
|
|
|
While logged in at a terminal session as expo on expo.survex.,com
|
|
|
|
$ mysql -h localhost -u expo -p<password>
|
|
will get you the MariasDb command prompt: https://www.hostwinds.com/guide/how-to-use-mysql-mariadb-from-command-line/
|
|
|
|
then (Note the SEMICOLONS !):
|
|
>drop database troggle;
|
|
>create database troggle;
|
|
>quit
|
|
Somewhere I have notes for the GRANT PRIVS type runes...
|
|
|
|
Ah yes:
|
|
CREATE DATABASE troggle;
|
|
GRANT ALL PRIVILEGES ON troggle.* TO 'expo'@'localhost' IDENTIFIED BY 'somepassword'; FLUSH PRIVILEGES; (at mysql root prompt)
|
|
|
|
(explained on https://chartio.com/resources/tutorials/how-to-grant-all-privileges-on-a-database-in-mysql/)
|
|
(but you need to create the database too)
|
|
|
|
The GRANT ALL PRIVILEGES bit requires you to logon in to MariaDB as root. sudo doesn't cut it.
|
|
these permissions are set in a different 'info' database which usually is untouched even if database troggle gets creamed.
|
|
|
|
|
|
PERMISSIONS
|
|
https://linuxize.com/post/usermod-command-in-linux/
|
|
|
|
sudo usermod -a expo www-data
|
|
adds expo to the www-data group which is what the webserver uses, and thus so the user troggle is acting as when
|
|
running live.
|
|
|
|
sudo usermod -a expo expocvs
|
|
the expocvs group is used for git & hg
|
|
|
|
all the users should bve in this group
|
|
|
|
|
|
Running a Troggle server with Apache
|
|
------------------------------------
|
|
Troggle also needs these aliases to be configured. These are set in
|
|
/home/expo/config/apache/expo.conf
|
|
on the expo server.
|
|
|
|
At least these need setting:
|
|
DocumentRoot /home/expo/expoweb
|
|
WSGIScriptAlias / /home/expo/troggle/wsgi.py
|
|
<Directory /home/expo/troggle>
|
|
<Files wsgi.py>
|
|
Require all granted
|
|
</Files>
|
|
</Directory>
|
|
|
|
Alias /expofiles /home/expo/expofiles
|
|
Alias /photos /home/expo/webphotos
|
|
Alias /map /home/expo/expoweb/map
|
|
Alias /javascript /usr/share/javascript
|
|
Alias /static/ /home/expo/static/
|
|
ScriptAlias /repositories /home/expo/config/apache/services/hgweb/hgweb.cgi
|
|
|
|
(The last is just for mercurial which will be remoived during 2020).
|
|
|
|
These two are not necessary as Django will serve these (see urls.py), but
|
|
it may be faster for apache to serve them first:
|
|
Alias /expofiles /home/expo/expofiles
|
|
Alias /static/ /home/expo/static/
|
|
|
|
|
|
Unlike the django "manage.py runserver" method, apache requires a restart before it will use
|
|
any changed files:
|
|
|
|
sudo service apache2 restart
|
|
|
|
Olly's comments 20 July 2020:
|
|
olly: looking at /lib/systemd/system/apache2.service suggests so
|
|
|
|
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.
|
|
|
|
pip install pygraphviz
|
|
pip install pyparsing pydot # installs fine
|
|
django extension graph_models # https://django-extensions.readthedocs.io/en/latest/graph_models.html |