<p>For troggle itself, you need a linux machine. We all use Debian or Debian-derived machines (Debian itself, Ubuntu, Xubuntu etc.) but other forms of linux may work. Running Debian or Ubuntu under WSL on Windows 10 works fine.
<p>You need to already know really quite a lot about what troggle does, and how it is used in practice. Also you will have installed quite a lot of the software such as tunnel, therion, survex etc. as documented in <ahref="../computing/yourlaptop.html">your laptop configuration</a>. In particular read the information there about VS code and git.
<p>If you don't already know how to do this, then you should probably not be attempting to work on the troggle code. But in case you are an experienced linux user who has always had someone else set up the system for them, then Ubuntu is the easiest and more forgiving to install, either directly on the computer or inside WSL. Because we are using fairly old releases of Django, you will want Ubuntu-20.04
<p>and familiarise yourself with the directory structure on the expo server, which we will be duplicating (partly) as docmented in <ahref="serverconfig.html">The Expo Server</a>. We are not here doing a full install of all the software and scripts on the server, just the minimum to run, test and debug troggle on Django.
<p>Python is not installed by default usually, and in any case we need specific versions to be installed. For Ubuntu 20.04 the default is python3.9 but this is incompatible with standard debian Buster which is what is live on our server, so we also need python3.7 . If you are planning on helping the migration of troggle from debian Buster (v10) to Bullseye (v11) then you will also want python3.8 .
<p>If you do not have a local copy of the 40GB /expofiles/, don't worry. Later on we can set 'EXPOFILESREMOTE = True' and your test system will use the live expofiles on expo.survex.com (read only).
and you will more easily be able to manage problems with incompatible versions of Django plugins as installing and upgrading the dependent packages is very fast.
a <var>venv</var> specifically for python 3.7 (which is the standard version on our server which is running unmodified Buster (debian v10) and <ahref="https://docs.djangoproject.com/en/3.2/releases/2.2/">Django 2.2.19</a>. See the <ahref="https://docs.python.org/3.7/library/venv.html">standard python documentation on venv</a> for python 3.7.12. You can upgrade the version of python installed within pip venv but not downgrade. So get that first venv installed right by explicitly stating the python version to create it <var>python3.7 -m venv py37d22</var>.
Note that we are creating it as a sibling folder to /expoweb/ . Note also that up to now we have been using 'sudo ..' but for installing things inside the venv we do not use 'sudo ..':
have installed troggle, Django and dependencies. You will get a warning that you have an out of date version of pipbut this is as we want: we are using a version of pip appropriate for the older version of python within
dependencies appropriate for troggle - because you have not yet cloned the troggle repo. So the first time it is easiest to just create requirements.txt yourself with a text editor. Without using git yourself, you can get the file from the website at <ahref="http://expo.survex.com/repositories/troggle/.git/tree/requirements.txt">requirements.txt</a>. If you have already cloned all the repos, then just copy it.
<p>The <var>:troggle:</var> repo is the python source code for troggle. This is what you will be editing. There are over 8,000 lines of python code (excluding comments and blank lines) and over 2,000 lines of HTML/Django template code. This is over 600 files in over 400 folders, but only 38MB in size.
<p>Follow this link to <ahref="../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.
<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>
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 <ahref="trogdjangup.html">our Django versions page</a>.
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:
localsettings.py is not stored in git, but the copy on the server does have the correct passwords.
So use sFTP to download localsettings.py from expo.survex.com to get these.
<p>
We have at one time made localsettings in /_deploy/ appropriate for
<ul>
<li>debian (server install, not development)
<li>Ubuntu
<li>Ubuntu under WSL (Windows System for Linux)
<li>docker container
<li>potatohut (local network only)
</ul>
<p>
WARNING: only the WSL and debian variants are current in October 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
<p>Now edit localsettings.py and insert useful values for EXPOUSERPASS [e.g. cavey:beery], EXPOADMINUSERPASS [e.g. beery:cavey], SECRET_KEY. SECRET_KEY can be anything, it just has to be unique to each installation and invisible to anyone not a developer.
<p>Set <ahref="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>The test suite now tidies up after itself, so there should not be any temporary files left behind or local git commits that you will need to clean up.
<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, <em>after</em> you have done a full <ahref="trogimport.html">data import</a>:
Nearly half the code deals with importing and parsing data, so you need to test that a full data import works. Run the full data import <var>troggle$ python databaseReset.py reset R000</var>. It should take about 5 minutes to import everything. See <ahref="trogimport.html">Troggle Full Import</a> for what you should expect to see.
<p>You need to know git. Sorry, but there it is. See <ahref="../computing/repos.html">our git repositories</a> and <ahref="../computing/qstart-git.html">our git cheat sheet</a>.
<p>The public server uses a <ahref="https://mariadb.org/about/">MariaDB SQL database</a> and development is usually done using a single-user <ahref="https://sqlite.org/about.html">sqlite database</a> which is a standard Django option.
You will find it very, very useful to see what is going on if you look directly at the data in the database (just a single file in the sqlite case) and browse the data in the tables. This is vital when doing Django migrations between Django versions. A light-weight, simple db browser is <ahref="https://sqlitebrowser.org/">DB Browser for SQLite</a>. Connecting directly the the MariaDB database with a control panel or <ahref="https://www.mysql.com/products/workbench/">workbench</a> gives even more tools and documentation capabilities. See the <ahref="serverconfig.html">troggle server documentation</a> for how to install MariaDB.
