<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 or 11 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 git and set up the key-pair as documented in <ahref="../computing/bulkupdatelaptop.html">your bulk update laptop configuration</a>. In particular read the information there about VS code and git.
If you have never done any bulk updates, and don't understand git, but want to look at the code and maybe run it, then there is a shortcut. You do not actually need to do all the Bulk Update machine configuration first.
<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. Ubuntu installs python and various essential python dev tools by default.
<li>Configure ☯<ahref="../computing/wsllaptop.html">WSL on a WIndows laptop</a>. The standard documentation for Ubuntu or debian below all works, but you should first skim the
<p>Before you do anything else, get yourself set up with a <ahref="../computing/keyexchange.html">key-pair</a> to access the software on the expo server properly.
<p>Do 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>You will run <var>os-trog24.04.sh</var> just once to install all the basics,and you will run <var>venv-trog.sh</var> just once initially.
<p>We have two configurations for the virtual environment: 'dev' which uses the latest python and Django for speed, and 'server' which mimics the versions currently running on the server. [In December 2024 Django is 5 releases ahead of the version on the server (5.1 versus 3.2). Each has a list of ancilliary packages with the appropriate versions in dev.toml and server.toml.] <var>venv-trog.sh</var> deals with all this python-specific stuff, libraries and Django plug-ins.
<p><var>os-trog.sh</var> takes a few minutes: it installs the subset of /expofiles/ you need to work with troggle. If you now want to install survex, therion etc. then run <var>os-survey.sh</var>, and go away for an hour, as these drag in a huge number of dependencies and installs all of /expofiles/ except the photos and Martin's mapapp.
provisioning so that systems are rebuilt cleanly. <ahref="http://www.cuyc.org.uk">CUYC</a> (who also use Django) have a bash script which sets up a new django
development system. We should copy that in the first instance. Alas, we haven't got around to doing any of this yet. However <var>uv</var> now makes everything much, much simpler than when were were using <var>pip</var>.
<br>copy it from the .git repo online to get hold of it. Run it in <var>/home/username</var> and it will create a folder <var>expo</var> and clone all the repositories into it after installing the software you need. It installs some of <var>expofiles</var> but not <var>expofiles/photos/</var>.
<p>You can, if you like, have the expo photo archive collection somewhere else, not inside <var>expofiles</var>, on a troggle development machine. To do this set the PHOTOS_ROOT appropriately in <var>troggle/localsettings.py</var>. By default it is <var>PHOTOS_ROOT = EXPOFILES / 'photos'</var>. This is handy if you want everything else in expofiles in your Linux home drive for speed, but don't care about speed for the 29GB of photos which can sit on an SDdrive.
<p>We do <em>not</em> install Django at the system level using <var>sudo apt install django</var>. We will be installing two variants of Django and python in a separate virtual
environment (a 'venv'); not in the main linux system. The reasons why are indicated in the cartoon to the right and explained in <ahref="https://nielscautaerts.xyz/python-dependency-management-is-a-dumpster-fire.html">"python dependency management is a dumpster fire".</a>
<p>To prevent compatibility issues when deploying our code, we test using the same libraries that run on expo.survex.com. In December 2024 expo.survex.com uses Python 3.11.2 and Django 3.2. However on our laptops we develop with Python 3.13 and Django 5 to get plenty of warning of future incompatibilities. Additionally, these newer versions are faster.
which resolves the dependences for the packages used with the 'dev' (development) configuration, installs anything missing (including python interpreters), and sets up links to the correct versions of python and django.
If it crashes though, you have not managed to install the software completely.
If you get an error when running
<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:
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/4.0/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 has ~90 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.
<p>When Ubuntu was running on WSL1, it did not use systemctl. Now Ubuntu24.04 does ue systemctl so we should be able to use the same configuration as the server.. [untried as yet].
<divstyle="margin-left:15%">
<h4>Previously..</h4>
<p>So under WSL1 you needed specific instructions for installing MariaDB under WSL,
<p>That is because we need to install the python tools that talk to mariadb. And while it 'will just work' for python3.9, the standard installed on the distro, with python3.10 it is a bit more work.
but you don't need these for most troggle development: copies of what is needed are in the troggle git repo. One example that is not in the troggle git repo is <ahref="https://aardgoose.github.io/CaveView.js/installation.html">"CaveView"</a>.
