<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>The install script (see below) will create the dev and server-mimic folders which will be virtual environments.
<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-trog.sh</var> just once to install the basics, but you will run <var>venv-trog.sh</var> every time you fire up a new python version/django version combination or play with the versions of the imported packages as listed in <var>requirements.txt</var>.
<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. These will be setup for you by <var>venv-trog.sh</var>.
<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>
<p>If you are using a very old laptop, you may have to run Ubuntu in WSL1 rather than WSL2. WSL2 requires virtualisation features that your hardware may not support if it is more than about 10 years old.
<ahref="../computing/winlaptop.html">Windows expo laptop</a> configuration too. <em>So far as expo software</em> is concerned, WSL1 and WSL2 behave identically. <p>...Except for file permissions, which can cost you a day of frustration if you are unlucky.
The trick is to make sure that all the files in your development folders, e.g. <var>C:\expo\</var> which contains your repos e.g. <var>C:\expo\troggle\</var> are owned in the Windows system by the default Windows user e.g. <var>MACHINENAME\philip</var> and owned in the Linux system e.g. <var>/mnt/c/expo/</var> by the default Linux user, e.g. <var>philip:philip</var> using <br><var>sudo chown -Rhv philip:philip *</var>
<br>
and then <em>reboot your machine</em> as this doesn't seem to properly take effect until you do that.
<p>
See also <ahref="https://learn.microsoft.com/en-us/windows/wsl/file-permissions">WSL File Permissions</a>.
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.
<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>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.
