From cc4128a124378e6ad47795c9ac644c39dbc8cc79 Mon Sep 17 00:00:00 2001 From: Philip Sargent Date: Tue, 25 Feb 2020 02:14:23 +0000 Subject: [PATCH] Minimal laptop setup - the gateway drug --- handbook/computing/basiclaptop.html | 73 ++++++++++++++++++++++++++++ handbook/computing/qstart-git.html | 75 +++++++++++++++++++++++++++++ handbook/computing/qstart-hg.html | 13 ++--- handbook/computing/yourlaptop.html | 7 --- handbook/index.htm | 3 +- handbook/manual.html | 52 ++++++++------------ handbook/tortoise/tortoise-win.htm | 1 + 7 files changed, 174 insertions(+), 50 deletions(-) create mode 100644 handbook/computing/basiclaptop.html create mode 100644 handbook/computing/qstart-git.html diff --git a/handbook/computing/basiclaptop.html b/handbook/computing/basiclaptop.html new file mode 100644 index 000000000..2d0d1e8f1 --- /dev/null +++ b/handbook/computing/basiclaptop.html @@ -0,0 +1,73 @@ + + + + +CUCC Expedition Handbook: Programmers manual + + + +

CUCC Expedition Handbook - Minimal laptop

+ +

Setting up a minimal machine to work with Expo data

+ +

Overview

+ +

You need to do this:

+
    +
  1. Register an SSH key with an expo nerd (i.e 'get a login').
    2. +
  2. Install git version control software to download ("clone"), view and edit caving data.
    3. +
  3. Clone three expo repositories so you have the files on your machine.
    4. +
  4. Install survex, and therion or tunnel for editing cave data. +
+ +

Once you have got this working, and if it doesn't do what you want or you don't understand how to use it, +look at the full laptop configuration for everything else. +And please write some documentation for the next person in your situation. + +

Cheat lists and quick reminders

+ + +

Software

+

Download this software (short list): +

+ +

Configuration

+ +

Follow this link to register a key with the expo server to get upload (i.e. read/write) access. +Do this first, Without it none of git, mercurial, scp, ftp or rsync will work. + +

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.

+ + +

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

Learning how to use this software

+ + + + + + + +
+ + + diff --git a/handbook/computing/qstart-git.html b/handbook/computing/qstart-git.html new file mode 100644 index 000000000..06f4212d7 --- /dev/null +++ b/handbook/computing/qstart-git.html @@ -0,0 +1,75 @@ + + + + +Handbook placeholder page + + + +

CUCC Expedition Handbook - Git Quick

+ +

Quick Reminder - Git

+

Version Control Software Reminders

+

This is NOT a tutorial. This is a set of reminders for people who already know all this stuff. + +

Since 2019 all use of version control software requires that you +have key-pair setup already set up before any of this will work on your own machine. + +

NOT CHECKED _ TO BE EDITED BY A git NERD TO MAKE IT WORK. DO NOT DO THIS UNTIL THAT HAS BEEN DONE +- check that you can get ssh working before trying to run git too + +

If you can get to the expo laptop try these commands on that first as the key exchange has already been done. +

+
expoweb (The data management system)
+
+ git clone ssh://expo@expo.survex.com/expoweb (read/write)
+ git clone http://expo.survex.com/repositories/home/expo/expoweb/ (read-only checkout) +
+ +
troggle (The data management system backend)
+
+ git clone ssh://expo@expo.survex.com/troggle (read/write)
+ git clone http://expo.survex.com/repositories/home/expo/troggle/ (read-only checkout) +
+ +
loser (The survey data)
+
+ git clone ssh://expo@expo.survex.com/loser (read/write)
+ git clone http://expo.survex.com/repositories/home/expo/loser/ (read-only) +
+ +
drawings
+
+ git clone ssh://expo@expo.survex.com/drawings (read/write)
+ git clone http://expo.survex.com/repositories/home/expo/drawings/ (read-only) +
+
+

Using git in Windows

+ + +

Once you've downloaded and installed a git client, the first step is to create what is called a checkout of the data management system. This creates a copy on your machine which you can edit to your heart's content. The command to initially check out ('clone') the entire expo data management system is:

+ +

git clone ssh://expo@expo.survex.com/expoweb

+ +

for subsequent updates

+ +

git update

+ +

will generally do the trick.

+ +

ssh://expo@expo.survex.com/expoweb

+ +

After you've made a change, commit it to you local copy with:

+ +

git commit (you can specify filenames to be specific)

+ +

The first time you do this on a Windows machineit will probably not work as it does not recognise the server. +Fix this by running putty (downloading it from https://www.chiark.greenend.org.uk/~sgtatham/putty/), and connecting to the server 'expo@expo.survex.com' (on port 22). Confirm that this is the right server. +If you succeed in getting a shell prompt then ssh connection are working and git should be able to clone the repo, and send changes back.

+ + +
+ + + + diff --git a/handbook/computing/qstart-hg.html b/handbook/computing/qstart-hg.html index 6297c0ce2..42ddeddcd 100644 --- a/handbook/computing/qstart-hg.html +++ b/handbook/computing/qstart-hg.html @@ -35,10 +35,10 @@ have key-pair setup already set up before any of hg clone http://expo.survex.com/repositories/home/expo/loser/ (read-only) -
tunneldata (The Tunnel drawings)
+
drawings
- hg clone ssh://expo@expo.survex.com/tunneldata (read/write)
- hg clone http://expo.survex.com/repositories/home/expo/expoweb/ (read-only) + hg clone ssh://expo@expo.survex.com/drawings (read/write)
+ hg clone http://expo.survex.com/repositories/home/expo/drawings/ (read-only)

Using Mercurial/TortoiseHg in Windows

@@ -84,13 +84,6 @@ then restart nautilus nautilus -q. If it works, you'll be able to see t
- - diff --git a/handbook/computing/yourlaptop.html b/handbook/computing/yourlaptop.html index 2ad4471f5..ce70c3f02 100644 --- a/handbook/computing/yourlaptop.html +++ b/handbook/computing/yourlaptop.html @@ -176,12 +176,5 @@ a wiki on github discussing workflows to generate centerlines, GEOTIFF and QGIS
- diff --git a/handbook/index.htm b/handbook/index.htm index 998e24ace..df7260d89 100644 --- a/handbook/index.htm +++ b/handbook/index.htm @@ -53,7 +53,8 @@ This is a scientific expedition - the Austrian government allows us to wander ar
  • Recording newly found caves - What and how to record. (important!)
  • Logbook - Adding trip notes and cave descriptions.
    • -
  • Configuring a new laptop - Experts only: software and configuration.
    • +
  • Using your own laptop - Minimal setup to download and upload stuff.
    • +
  • Configuring everything on a new laptop - It's a lot. This is not the place to start

    • diff --git a/handbook/manual.html b/handbook/manual.html index d98da954d..8d9ae6c95 100644 --- a/handbook/manual.html +++ b/handbook/manual.html @@ -130,7 +130,8 @@ complicated process. At a minimum you will be an experienced software nerd alrea You will have done the key-pair setup process - which you can only do entirely on your own if you have access to the expo laptop. -

    See setting up your own laptop for the full list of software we use and where to get it. +

    See setting up a minimal laptop for a short list of software. This assumes you know how to use it all. +
    See setting up your own laptop for the full list of software we use and where to get it.

    Note that the instructions are primarily for people using Linux with some help for those using Windows. If you are a Mac user then you are on your own. @@ -209,31 +210,21 @@ see if you are logged into troggle. In general the dynamically-generated pages, caves which are generated from the cave survey data, can not be edited in this way, but forms are provided for some types of these like 'caves'.

    -

    -[ui]
    username = Firstname Lastname <myemail@example.com> -

    +

    Cheat lists and quick reminders

    + -

    The commit has stored the changes in your local Mercurial DVCS, but it has not sent anything back to the server. To do that you need to:

    +

    Simple changes to static HTML files will take effect immediately (or as soon as the hg update hack is done, but this will disappear when we move entirely to git), +but changes to dynamically-generated files - cave descriptions, QM lists etc. - +will not take effect, until a nerd runs the expoweb-update script on the server.

    -

    hg push

    +

    The expoweb & drawings import scripts

    -

    Before pushing, you should do an hg pull to sync with upstream first. If someone else has edited the same files you may also need to do:

    - -

    hg merge

    - -

    (and sort out any conflicts if you've both edited the same file) before pushing again

    - -

    Simple changes to static files will take effect immediately, but changes to dynamically-generated files (cave descriptions, QM lists etc) will not take effect, until the server runs the expoweb-update script.

    - - - - - -

    The expoweb-update script

    - -

    The script at the heart of the data management system update mechanism is a makefile that runs the various generation scripts. It is run every 15 minutes as a cron job (at 0,15,30 and 45 past the hour), but if you want to force an update more quickly you can run it he

    - -

    The scripts are generally under the 'noinfo' section of the site just because that has (had) some access control. This will get changed to something more sensible at some point

    +

    The import scripts for the cave data are currently (Feb.2020) run manually by a nerd. So if you enter cave data,logbooks or survey scans you won't see the result +until a nerd has been placated.

    Updating cave pages

    @@ -243,7 +234,9 @@ cave files in noinfo/cave_data/ and noinfo/entrance_data/. These files are named -.html (where area is 1623 or 1626). These files are processed by troggle. Use python databaseReset.py caves in /expofiles/troggle/ to update the site/database after -editing these files.

    +editing these files. +Use python databaseReset.py + on its own to get a list of command options and brief explanations.

    Clicking on 'New cave' (at the bottom of the cave index) lets you enter a new cave. Info on how to enter new caves has been split into its own page.

    @@ -258,7 +251,9 @@ superseded in 2012).

    /expoweb/years/ -

    which contains a number of files used to manage and record that year's expo. Have a look at expoweb/years/2018/ for a recent well-documented expo (the weather was good). Files are added and edited using the version control system for the expoweb repository.

    +

    which contains a number of files used to manage and record that year's expo. Have a look at +expoweb/years/2018/ for a recent well-documented expo (the weather was good). +Files are added and edited using the version control system for the expoweb repository.

    To create a new 'year' for next year's expo see adding a new year. @@ -267,13 +262,6 @@ superseded in 2012).

    Maintaining the survey status table

    See the documentation on updating the online surveyscans folders using the lever-arch file of plastic wallets. -

    This below is obsolete: -

    -

    Cave pages and handbook menu design

    See the menu design history and proposals page on where we are and what we might do to improveand fix menus. diff --git a/handbook/tortoise/tortoise-win.htm b/handbook/tortoise/tortoise-win.htm index 3e467ab43..b37040e02 100644 --- a/handbook/tortoise/tortoise-win.htm +++ b/handbook/tortoise/tortoise-win.htm @@ -11,6 +11,7 @@

    Windows: TortoiseHg and PuTTy

    +

    THIS ARTICLE TO BE SPLIT - PuTTy STUFF VALID BUT Hg SHORTLY TO BE OBSOLETEStruggling to get TortoiseHg to work on Windows (v10)? Here’s a quick guide which I hope explains how to sort it all out.