From 3d53810df4dc6646f566ab562c6f3fbe3c425af0 Mon Sep 17 00:00:00 2001 From: Philip Sargent Date: Wed, 17 Jul 2019 16:07:52 +0200 Subject: [PATCH] Documentation fixes for ssh key needs --- handbook/computing/qstart-hg.html | 96 +++++++++++++++++++ handbook/manual.html | 149 ++++++++++++----------------- handbook/tortoise/tortoise-win.htm | 8 +- 3 files changed, 164 insertions(+), 89 deletions(-) create mode 100644 handbook/computing/qstart-hg.html diff --git a/handbook/computing/qstart-hg.html b/handbook/computing/qstart-hg.html new file mode 100644 index 000000000..436b7eb16 --- /dev/null +++ b/handbook/computing/qstart-hg.html @@ -0,0 +1,96 @@ + + + +Handbook placeholder page + + + +

CUCC Expedition Handbook - Mercurial Quick

+ +

Quick Reminder - Mercurial

+

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 cyptographic key exchnage already set up before any of this will work on your own machine. + +

You can, however, do all this on the expo laptop as this has already been configured with the right keys. +

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

Using Mercurial/TortoiseHg in Windows

+ +

Read the instructions for setting up TortoiseHG in Tortoise-on-Windows. But this won't work at all until you set up the key exchange using PuTty/Pageant. +

In Windows: install Mercurial and TortoiseHg of the relevant flavour from https://tortoisehg.bitbucket.io/ (ignoring antivirus/Windows warnings). This will install a submenu in your Programs menu)

+ +

To start cloning a repository: first create the folders you need for the repositories you are going to use, e.g. D:\CUCC-Expo\loser and D:\CUCC-Expo\expoweb. Then start TortoiseHg Workbench from your Programs menu, click File -> Clone repository, a dialogue box will appear. In the Source box type

+ + + +

What follows is for Linux. If you are running Windows then see below Using Mercurial/TortoiseHg in Windows. + +

Mercurial can be used from the command line, but if you prefer a GUI, TourtoiseHg is highly recommended on all OSes.

+ +

Linux: Install mercurial and tortoisehg-nautilus from synaptic, +then restart nautilus nautilus -q. If it works, you'll be able to see the menus of tortoise within your Nautilus windows.

+ +

Once you've downloaded and installed a 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:

+ +

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

+ +

for subsequent updates

+ +

hg update

+ +

will generally do the trick.

+ +

In TortoiseHg, merely right-click on a folder you want to check out to, choose "Mercurial checkout," and enter

+ +

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

+ +

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

+ +

hg commit (you can specify filenames to be specific)

+ +

or right clicking on the folder and going to commit in TortoiseHg. Mercurial can't always work out who you are. If you see a message like "abort: no username supplied" it was probably not set up to deduce that from your environment. It's easiest to give it the info in a config file at ~/.hgrc (create it if it doesn't exist, or add these lines if it already does) containing something like

+

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

+ +

for expoweb (or similar for the other repositories). In the Destination box type whatever destination you want your local copies to live in on your laptop e.g. D:\CUCC-Expo\expoweb. Hit Clone, and it should hopefully prompt you for the usual beery password. + +

The first time you do this it 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 TortoiseHg should be able to clone the repo, and send changes back.

+ + +
+ + + + diff --git a/handbook/manual.html b/handbook/manual.html index fa8ea2af9..7bc837f8b 100644 --- a/handbook/manual.html +++ b/handbook/manual.html @@ -1,13 +1,20 @@ -CUCC Expedition Handbook: Online system manual +CUCC Expedition Handbook: Programmers manual

CUCC Expedition Handbook - Online systems

-

Expo Online Systems Manual

+

Expo Data Maintenance Manual

-

Expo data management systems manual

+

Expo data management programmers' manual

+ +

Editing the expo data management system is an adventure. Until 2007, there was no guide which explained the whole thing as a functioning system. Learning @@ -20,28 +27,32 @@ rather than referring to specific elements of the data management system, refer processes that a maintainer would want to do.

Note that to display the survey data you will need a copy of the survex software. -

Contents

+

Go elsewhere if this is what you want to know: +

+ +

Contents of this manual

  1. Getting a username and password
  2. The repositories
  3. How the data management system works
  4. Quick start
    5. -
  5. Editing the data management system
    6. -
  6. Using version control software in Windows
    7. +
  7. Modifying the data management system
  8. The expoweb-update script
  9. Updating cave pages
  10. Updating expo year pages
    11. -
  11. Adding typed logbooks
    12. -
  12. Uploading photos
  13. Ticking off QMs
  14. Maintaining the survey status table
  15. Automation
    16. -
  16. Archived updates
    17. +
Appendices:

Getting a username and password

@@ -50,23 +61,33 @@ Appendices: with a cavey:beery password. Ask someone if this isn't enough clue for you. This password is important for security. The whole site will get hacked by spammers or worse if you are not careful with it. Use a secure method for passing it on to others that need to know (i.e not unencrypted email), don't publish it anywhere, don't check it in to the data management system by accident. A lot of people use it and changing it is a pain for everyone so do take a bit of care.

-

Note that you don't need a password to view most things, but you will need one to change them

+

This password is all you need to log in to troggle and to use the control panel. But if you want to edit the software itself, or update webpages, then +you will also need to get a cryptographic key and register it with the server. See key exchange for details. + +

Unfortunately, pushing cave data to ::loser:: and ::drawings:: also needs a key. So cavers entering their cave survey data +currently have to use a machine on which this already set up. These machines are +the expo laptop and the laptop 'aziaphale' which live in the potato hut during expo. + +

The repositories

All the expo data is contained in 4 "repositories" at -expo.survex.com. This is currently hosted on a server at the university. We use a distributed version control system (DVCS) to manage these repositories because this allows simultaneous collaborative editing and keeps track of all changes so we can roll back and have branches if needed.

+expo.survex.com. This is currently hosted on a free virtual server we have blagged on a server farm. +We use a distributed version control system (DVCS) to manage these repositories because this allows simultaneous collaborative +editing and keeps track of all changes so we can roll back and have branches if needed.

The site has been split into four parts:

+

In 2019 we are in the process of migrating from mercurial to git for the repos.

All the scans, photos, presentations, fat documents and videos are stored just as files (not in version control) in 'expofiles'. See @@ -74,14 +95,21 @@ below for details on that.

How the data management system works

-

Part of the data management system is static HTML, but quite a lot is generated by scripts. So anything you check in which affects cave data or descriptions won't appear on the site until the data management system update scripts are run. This happens automatically every 30 mins, but you can also kick off a manual update. See 'The expoweb-update script' below for details.

+

Part of the data management system is static HTML, but quite a lot is generated by scripts. +So anything you check in which affects cave data or descriptions won't appear on the site until +the data management system update scripts are run. +This happens automatically every 30 mins, but you can also kick off a manual update. +See 'The expoweb-update script' below for details.

-

Also note that the data management system you see is its own Mercurial checkout (just like your local one) so that has to be 'pulled' from the server before your changes are reflected.

+

Also note that the ::expoweb:: web pages and cave data reports you see on the visible website +are not the same as the version-controlled "master" expoweb repo. +So in order that your committed and pushed changes become visible on the website, +they have to be 'pulled' from the repo onto the webserver before your changes are reflected.

Using 'Edit This Page'

This edits the file served by the webserver on -the expo server in Cambridge but it does not update the copy of the file in the -repository in expo.survex.com. To properly finish the job you need to +the expo server but it does not update the copy of the file in the +repository. To properly finish the job you need to