<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/wsllaptop.html">your bulk update 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. Ubuntu installs python and various essential python dev tools by default.
<li>In late 2022 you had to use the App Store <ahref="https://www.theregister.com/2022/11/23/wsl_microsoft_store_default_version/">
Windows Subsystem for Linux now packaged as a Microsoft Store app</a>,
<lI>But in 2024 <ahref="https://learn.microsoft.com/en-us/windows/wsl/install">it has changed again</a> and you just type <var>wsl --install</var>. at a terminal in Windows 11.
<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>Before the install scripts work on a bare Ubuntu installation, you will need to have git installed. This is in-built on Ubuntu 24.04 but on other (and earlier) Linux distros you will need to do:
<p>You will run <var>os-trog24.04.sh</var> just once to install 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.
<p><var>os-trog.sh</var> takes a few minutes initially, but then about an hour when it installs therion and tunnel as these drag in a huge number of dependencies.
<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 need to read this is you are doing anything even very slightly off the beaten tracke: <ahref="../computing/wsllaptop.html">WSL/Troggle</a>].<p>
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>.
<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 are revising this process. We are now (December 2024) using uv instead of pip, see
<ahref="https://nielscautaerts.xyz/python-dependency-management-is-a-dumpster-fire.html">"dumpster fire".</a>. DOCUMENTATION HERE NEEDS UPDATING URGENTLY, we do NOT use REQUIREMENTS.TXT
<p>In order to avoid compatability issues when deploying our code, we should develop using the same libraries that will be used in production of expo.survex.com. Expo.survex.com currently uses python 3.11.2, python 3.12 (standard with Ubuntu 24.04) is backwardly compatable as long as you do not use any new functions it should be fine. Venv allows us to specify which python libraries to use.</p>
<p>[We also develop with Django 5 even though the server is still running Django 3.2, but so long as we are carefule, and test code before pushng to the server, this is fine.]
<p>In case you have python version problems with venv, look at the instructions for <ahref="/handbook/computing/wsllaptop.html_edit">python3.11 on WSL2</a>.
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>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>.
