diff --git a/handbook/computing/basiclaptop.html b/handbook/computing/basiclaptop.html index 1f527ecb0..afbc7c59f 100644 --- a/handbook/computing/basiclaptop.html +++ b/handbook/computing/basiclaptop.html @@ -105,8 +105,12 @@ careful when naming files and survex names and be full laptop instructions - - +

FTP

+

It is necessary to use scp or sftp to manage large collections of files in 'expofiles' + See Experts: Uploading files, + Uploading files and Uploading GPS tracks. + Only machines which have done the key-pair setup process can do scp, sftp or rsync. +

diff --git a/handbook/computing/yourlaptop.html b/handbook/computing/yourlaptop.html index 95ea1b84d..22326cc6a 100644 --- a/handbook/computing/yourlaptop.html +++ b/handbook/computing/yourlaptop.html @@ -8,42 +8,54 @@

CUCC Expedition Handbook - Your laptop

-

Setting up a machine for Expo

+

Cave survey software - beyond the basics

-

Overview

+

Phones and laptops

-

The main things you need to do to get set up are:

+ +

Your Android phone

+

Everyone has a phone pretty much, and everyone should have GPS enabled for safety. See the expo GPS configuration pages. +

There are several cave survey apps which run on a phone. We don't yet have a well documented way of using these +with the expo survey data workflow.

-

For a quicker, shorter guide to only the most basic setup, see the -

-first. -

-

This is a complete list for doing software development of survex and tunnel - (but not troggle) as well as accessing expo data and doing survey data reduction. -This page needs to be edited so that the software development stuff is separated -out into separate pages.

-So that the people who only want to do cave data stuff -don't see a lot of complex stuff they don't need.

+
  • OsmAnd - a GPS app. +
  • GPSessentials - another GPS app. +
  • Ape@Map - another GPS app, compatible with Kompass commerical map sand used by Austrian cavers -

    Operating Systems

    +
  • TopoDroid makes cave surveys with the DistoX. +
  • Cave3D is a Therion 3D viewer. +
  • ThManager organizes single surveys, exported by TopoDroid, into Therion projects encoded by Therion "thconfig" files. + + +

    You can also use a phone to upload files and manage version control on the server. This is not the place to start, but if you are already doing this on your own laptop then these can be useful: +

    + +

    Your laptop

    + +

    You will already have configured your laptop to do all the basic stuff using the +basic Expo laptop guide. + + +

    This is an attempt at a complete set of optional software for using survex, tunnel, therion, photos and GPS tracks to document our caves: using the existing data archive and processing new survey data. +

    If you want to do software development instead, go to configuring a troggle development machine. + +

    + +

    This page documents what else you might find useful if the basic laptop setup does not do what you need. + +

    Windows, Macs and Linux

    Software

    @@ -56,8 +68,7 @@ but all the recommended software here is open source (and please don't install p

    The list of software:

    Nearly all our Austrian surveys have beeen produced using Tunnel (or were hand-drawn) but many smaller caves and some areas of SMKsystem are done with Therion because Therion does elevations and Tunnel doesn't. Expo has a policy decision on which to use: if it is an entirely new disconnected cave, then use Therion. If it is a passage in a cave where previously we used Tunnel, then use Tunnel. See also Comparison of Tunnel to Other Cave Software.

    -

    Note that on a Debian/Ubuntu machine you should normally install the versions that come with the distro (i.e. install using 'apt install xxx', not be downloading things from the above sites

    +

    For Linux users only:

    - +

    Note that on a Debian/Ubuntu machine you should normally install the versions that come with the distro (i.e. install using 'apt install xxx', not be downloading things from the above sites

    For Windows users only:

    None of this works until you set up the key-pair setup using PuTty/Pageant. @@ -102,38 +115,28 @@ but all the recommended software here is open source (and please don't install p
  • WinScp can be used as an alternative to Filezilla if you like.
  • java - needed for GPSprune and CaveConverter. Has to be installed separately on a Windows machine.
  • Notepad++ or any other syntax-highlighting code editor for HTML and python. We have a syntax-highlighter to colourize .svx files, download it: survex.xml. -
  • python for windows. We moved from python 2.7 to python 3.7 in 2020; but we generally use the Linux environment on Windows machines (WSL) and use the python version there, not the Windows python. +

    Visual Studio Code editor

    A short note about the phenomenon of VS code is in order. Not really for beginners but here are instructions for configuring it for python. In case you didn't know, by 2019 over half of all software developers used this editor for their Linux and Windows work and it is undoubtedly more now. -

    For Android phones:

    - +

    Configuration

    - +

    Idiots guide to setting up git for expo + - PDF - Brendan's guide. Uses PuTTy and GitKraken. +

    You need to register a key with the expo server to get upload (i.e. read/write) access. Do this first, Without it none of git, scp, ftp or rsync will work. You can do this entirely on your own if you have access to the expo laptop to upload and install the public key generated by your laptop.

    On a Windows machine you will need to configure pageant (the putty authentication agent) to run at startup to load your key. Note that you are loading your private key, the .ppk file, into pageant and that this key never leaves your laptop.

    -

    Idiots guide to setting up git for expo - - PDF - Brendan's guide. Uses PuTTy and GitKraken. -

    The above gets the command-line PuTTY tools (ssd, sftp, pscp) running, but doesn't get rsync working. You might like to try this (untested).

    + +

    Full illustrated instructions:

    @@ -144,52 +147,10 @@ to Installing Filezilla.
    • +

    The above gets the command-line PuTTY tools (ssd, sftp, pscp) running, but doesn't get rsync working. You might like to try this (untested).

    +

    When using Windows please, please be excessively careful when naming files and survex names and be exceptionally careful when using rsync. -

    The handbook has documents where it is necessary to use scp or sftp to manage large files in 'expofiles'. - See Experts: Uploading files, - Uploading files and Uploading GPS tracks. - Only machines which have done the key-pair setup process can do scp, sftp or rsync. -

    - -

    For Linux and WSL Windows users doing software development only:

    -

    We run troggle on older, stable versions of software. So you will need to install similarly old software on your development machine. A default Debian install in October 2021 will install v11 (Bullseye) and python3.9 whereas we are still using v10 (Buster) and python3.7 for development. Buster is in LTS support until June 2024. Everything should work of course, but be aware. -

    - -

    Cheap hack for Linux

    -

    On a Linux machine, it will not be necessary once you have everything set-up correctly, but -a useful initial short-cut is to create 'mimic' symbolic links to directories to match those on the -server and the expo laptop. -(You should not rely on these as other people will have set up their machines differently.) -So, assuming that you are storing /expofiles/ on a different drive /mnt/f/ from everything else which is on /mnt/c/, and your machine has -no user expo:

    d /home
-sudo mkdir expo
-cd expo
-sudo ln -s /mnt/f/expofiles expofiles
-sudo ln -s /mnt/c/EXPO/expoweb expoweb
-sudo ln -s /mnt/c/EXPO/troggle troggle
-sudo ln -s /mnt/c/EXPO/loser loser
-sudo ln -s /mnt/c/EXPO/drawings drawings
-sudo ln -s /mnt/c/EXPO/expowebcache expowebcache
-sudo mkdir expowebcache/3d
-cd ..
-ls -tlA expo
-
    -where obviously you will be using your own locations for expofiles, expoweb, loser etc. instead of /mnt/d/EXPO... etc. This creates valid directory paths for, e.g. /home/expo/loser etc. -

    -

    Learning how to use this software

    @@ -217,7 +178,7 @@ where obviously you will be using your own locations for expofiles, expoweb, los

    Logins to external systems

    - #expo - public. An open-access + #expo - public. An open-access open-access IRC channel (ephemeral, not archived) for real-time discussions about everything but mostly software people. If you are having trouble using the software try here first.

    diff --git a/handbook/troggle/Django_Logo-420x180.png b/handbook/troggle/Django_Logo-420x180.png new file mode 100644 index 000000000..008d64b75 Binary files /dev/null and b/handbook/troggle/Django_Logo-420x180.png differ diff --git a/handbook/troggle/trogdjangup.html b/handbook/troggle/trogdjangup.html index 464d22bf6..4644616f8 100644 --- a/handbook/troggle/trogdjangup.html +++ b/handbook/troggle/trogdjangup.html @@ -23,21 +23,39 @@ End of support End of security fixes + + 4.2 LTS + April 2023 + December 2023 + April 2026 + + + 4.1 + August 2022 + April 2023 + December 2023 + + + 4.0 + December 2021 + August 2023 + April 2023 + 3.2 LTS - April 2021 + 3.2.8 December 2021 April 2024 3.1 - 3.1.7 + 3.1.13 April 2021 December 2021 3.0 - 3.0.13 + 3.0.14 August 2020 April 2021 @@ -47,12 +65,7 @@ December 2019 April 2022 - - 1.11 LTS - 1.11.29 - December 2017 - April 2020 - +

    Major, minor and releases

    diff --git a/handbook/troggle/troglaptop.html b/handbook/troggle/troglaptop.html index af4d9433e..2de71149b 100644 --- a/handbook/troggle/troglaptop.html +++ b/handbook/troggle/troglaptop.html @@ -17,13 +17,15 @@ your account will need to be added to the troggle project members list. Contact wookey at wookware dot org to get this set up.

    This page is a work in progess. Text will be moved here from -troggle logo 

     http://expo.survex.com/repositories/troggle/.git/tree/README.txt
 handbook/computing/yourlaptop.html
 handbook/troggle/trogdjangup.html
    +debian logo + +

    Installing linux

    If you don't already know how to do this, then you should probably not be attempting this. 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 @@ -39,11 +41,11 @@ handbook/troggle/trogdjangup.html is that WSL2 will be installed, but all our practical experience so far is with WSL1.

    Installing python

    -

    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, so we also need python3.7, -and also python3.8 if you are planning on migrating troggle from debian Buster (v10) to Bullseye (v11). +

    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, so we also need python3.7, if you are planning on migrating troggle from debian Buster (v10) to Bullseye (v11) then you will also want python3.8 . 

    sudo apt install python3 python3-pip
-sudo apt install python3.7
-sudo apt install python3.8
+sudo apt install software-properties-common
+sudo add-apt-repository ppa:deadsnakes/ppa
+sudo apt install python3.7 python3.7-venv python3.7-doc binutils binfmt-support
 sudo apt install sqlite3 sqlite3-doc
 sudo apt install survex
 cd /usr/bin
@@ -77,12 +79,13 @@ cd ..
 ls -tlA expo

    Installing Django and troggle

    +django logo

    The important point to note here is that unless you are doing something fairly trivial, or you are a git genius, it is sensible to set up a python virtual environments to hold duplicate copies of both troggle and django code. - Then you will be able to check that your edited version of troggle runs with old, current + Then you will be able to check very quickly that your edited version of troggle runs with old, current and pre-release versions of python and of django; - and you will more easily be able to manage problems with incompatible versions of django plugins. + 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.

    Installing a venv

    @@ -97,6 +100,7 @@ pip list -o

    The last command lists the default packages installed in the venv. This is for comparison later, after we 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 the venv. +troggle logo

    The first time you do this you can't complete the pip installation of django as you have not yet got the dependencies - 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. diff --git a/handbook/troggle/trognotes.html b/handbook/troggle/trognotes.html index 171f85707..a7d517565 100644 --- a/handbook/troggle/trognotes.html +++ b/handbook/troggle/trognotes.html @@ -64,8 +64,8 @@ to get involved in the progra

  • Use the online forms and reports together with 'survex' and 'therion' installed on your own laptop.
  • Get the 'expoadmin' password and explore the live system online: watch the data change in real time
  • Configure an ssh key and Filezilla or scp/sFTP. -
  • Configure a minimal expo laptop -
  • Configure a basic expo laptop +
  • Configure a basic expo laptop +
  • Configure a more cave software on your laptop
  • Configure a troggle development machine - a laptop where you have cloned the repos and installed django. Installing is the same as updating Django. See Troggle: updating Django.