CUCC Expedition Handbook - Your laptop

Setting up a machine for Expo

Overview

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

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.

Operating Systems

Software

Long-standing Expo policy is to use open tools and protocols so we can retain control of our own data over the long term. And not to require expo-goers to sign up to external services or spend money on software. So we use FOSS software. You can use other software on your own machine if it is format-compatible and exports data in the formats we want, but all the recommended software here is open source (and please don't install proprietary software on the 'expo laptop').

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:

For Linux and WSL (text mode only) Windows users only:

For Windows users only:

None of this works until you set up the key-pair setup using PuTty/Pageant.

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

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:

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.

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/d/, and your machine has no user expo:

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

Learning how to use this software


Cheat lists and quick reminders

Logins to external systems

#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.

Some expo survey stuff is tracked externally:

Complementary tools

When maintaining the HTML files in the expo handbook a link-checker is useful to report bad URLs (links to external sites go bad regularly) and to find orphaned pages with no in-links. The website has about 2,000 internal URLs in just the Tunnel wiki section alone.