<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. Ubuntu installs python and various essential python dev tools by default.
<p>The server is running fairly old, stable releases of Debian and Django, but you will probably want Ubuntu-22.04 which is compatible.
<li>[On 23 November 2022 a new way of installing and using WSL was announced, see <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> so all documentation on this expo site needs to be revised.]
<li>Install in <ahref="https://docs.microsoft.com/en-us/windows/wsl/install">WSL on Windows 10/11</a>
<li>Install <ahref="https://docs.microsoft.com/en-us/windows/wsl/install">Ubuntu 20.04 LTS</a> - can be done directly from wsl command line <var>wsl --install -d Ubuntu</var>.
<li>Install <ahref="https://linuxconfig.org/ubuntu-22-04-on-wsl-windows-subsystem-for-linux">Ubuntu 22.04 LTS</a> - must be done using MS App Store.
<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><p>[On 23 November 2022 a new way of installing and using WSL was announced, see <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> so all documentation on this expo site needs to be revised.]
<p>If you are using an 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 5 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>.
<p>But there is the significant danger that containers would get copied around and deployed without being properly cleaned up:
resulting in configuration drift and a <ahref="https://martinfowler.com/bliki/SnowflakeServer.html">snowflake server situation</a>.
File permissions are a big issue.
<p>We should do both: create a Docker system for getting started, then transition programmers to script-based or recipe-based
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.
<ahref="https://www.debian.org/releases/">Bookworm (v12)</a> to then you will also want the appropriate later versions of python e.g. 3.10 on Ubuntu 20.04 like this:
<p><b>Buggeration:</b> The <var>sudo add-apt-repository ppa:deadsnakes/ppa</var> line <ahref="https://opensource.com/article/22/9/deprecated-linux-apt-key">won't work</a> after Debian 11 or Ubuntu 22.04. So this handbook page will need to be changed to use the <ahref="https://askubuntu.com/questions/1286545/what-commands-exactly-should-replace-the-deprecated-apt-key">new method</a>. And this way of installing python3.10 is fine on Ubuntu but not on Debian, where you are stuck with 3.9 on Debian 11 (Bullseye). Note that default-jre is Java which is used by tunnel and <ahref="https://activityworkshop.net/software/gpsprune/download.html">gpsprune</a>.
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.
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.
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:
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 ~80 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.
