-------------------------------------------------------------------------------

readme file explaining how to set up cvs on Windows in order to access the
PAPCO cvs repository.

02/09/2005

-------------------------------------------------------------------------------

PAPCO has been put under a proper version control system, "cvs" (concurrent
version control system) since we have distributed developers.

cvs allows you to checkout a version of the code, run and modify it locally,
and then to upload your own changes. This can range from bug fixes to new
functionality to new modules.

With cvs you will have quick access to any bug fixes done elsewhwere, and to
the latest version of the code at any time. You can reprot a bug, it gets
fixed, and then you simply update your checked out version.

In order to use cvs you need to join the PAPCO developers group. Currently the
repository is maintained at lanl, and you will need a user account on our
systems to access the repository. This typically takes time, since we need to
get you a smartcard for this.

The Repository is on mrfrench.lanl.gov and is accessible only through SSH. We
will need the host IP of the host you will be working on as we will only open
ssh ports to known hosts. You access the repository thropugh ssh, for which
you can set up passwordless authentication (VERY useful). 

The remainder of this readme gives a brief overview of the installation steps
needed to get cvs and ssh up and running under windows. 

-------------------------------------------------------------------------------

1. Download / install programs

a) There is a nice gui for cvs for Windows called WinCVS. WinCVS can be freely
downloaded from 
http://sourceforge.net/projects/cvsgui/ 

The current version is WinCvs 1.3b24 and it's windows install file is in
../papco_lib/binaries/win32/WinCvs13b24_Bare.zip

Install it like a normal Windows application. Don't worry abut not having the
"python" stuff, you don't need it.


b) The PuTTy suite of programs can be used for ssh and authentication. It too
can be freely downloaded from 
http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html

The current version is 0.56 and it's windows install file is included
in   ../papco_lib/binaries/win32/putty-0.56-installer.exe

Install it like a normal Windows application

-------------------------------------------------------------------------------

2. Configuring ssh authenticated access through PuTTy

a). Try run the PuTTy terminal to see if you can actually get into mrfrench.
It's just called PuTTy either on your desktop or start -> Programs -> PuTTY ->
PuTTy.

Host Name: user@mrfrench.lanl.gov
where user is you user name on out LANL scheme, and the password is the same
too. 

You should get a terminal screen that asks you for your password, and lets you
"in". 

If you can't get in then please send the IP address of your host to
friedel@lanl.gov and ask for ssh access to mrfrench.


b) To allow authenticated passwordless entry you need to create the right
"keys" and put them in the right place on mrfrench. This is needed since
otherwise you'll need to enter yourpassword each time you performs cvs action,
which gets quite painfull...

i.First create your public/private key pair. Run start -> Programs -> PuTTY ->
PuTTygen. Follow the instruction on screen to Generate and save your keys.
Select the "SSH2DSA" type of key under "parameters" and hit "Generate".
change the Key comment to "your_host"
You can leave the passphrase blank or enter one - then you'll get asked to
enter the passphrase each time you want to use the key. A safety feature, not
really needed unless it's on your laptop.
Now hit "Save private key" to save the key, typically in My Documents, use
your "host_name" as name.ppk. 
You'll only have to save your public key if you want someone else to get
authenticated ssh access to your own host.

ii.Second: you need to copy that key to mrfrench.lanl.gov. On mrfrench that key
needs to be appended to or created in the file .ssh/authorized_keys. That file
MUST have permissions -rw------- only. 

The final entry onto the authorized keys file on mrfrench  needs to look like:

ssh-dss   friedel@cluster.bu.edu

with NO line breaks in it. The "friedel@cluster.bu.edu" is just a comment and
can be anything, typically you_user@your_host.whatever.net

c) Now you have to "tell" Windows ssh to use you public key when logging into
a remote site. PuTTy provides a "pageant" for this.
Run Run start -> Programs -> PuTTY -> Pageant. This puts the pageant into your
sytem tray, a little icon of a pc with a hat on. Double click it, and add the
previously saved key. If you entered a passphrase, you'll be asked it now.
Close the pageant. Your key will now be "served" for the rest of you
session. If you log out or restart your computer, you'll have to start the
pageant again.


c) Test your connection, like described under a). Now you should be able to
log in without entering a password. If that works, you're ready to checkout
PAPCO! 

-------------------------------------------------------------------------------

3. Configuring  WinCvs

a) Decide on a location where you want you PAPCO source to be checked out
to. Typically c:\idl

b) Start the application by double clicking your desktop icon or by start ->
Programs -> WinCvs -> WinCvs

c) In the wincvs gui, set up your preferecnes - Admin -> Preferecnes or
Ctrl+F1. 

Select the General Tab ->
  Set Authentication: ssh
      Hit the Settings button and tick SSH client:
          enter the location of plink from PuTTy,
          typically C:\Program Files\PuTTy\plink.exe
  Set Path: /u/friedel/cvs/papco
  Set Host address: mrfrench.lanl.gov
  Set User Name: your lanl scheme user name
  Your CVSROOT field should now look like 
    user@mrfrench.lanl.gov:/u/friedel/cvs/papco

Select the CVS Tab ->
  Set HOME to your PAPCO location: c:\idl

Hit OK.

d) Manually check out your first version of PAPCO. From the wincvs gui, select
Admin -> Command Line or Ctrl+L

Select the Settings Tab
  Set Force using the CVSROOT (-d)

In the command line field enter 

  cvs checkout -P papco

Hit OK.

Your checkout should commence automatically then with a bunch of 
"U papco/papco/......" messages displayed in the wincvs output window. 

This will now take a while...


When done, you shoudl see the papco directory tree listed in the workspace
window.

e) If all you wanted to do was download papco, you're done now. Exit wincvs
and follow the papco install instructions under
../pacco/papco_scripts/readme.install 

d) If you want to learn more on how to use cvs, then you need to do some
reading and learn both what cvs does and how, and how to work with wincvs.






