Difference between revisions of "Installation Guide"

From Bcontrol
(New page: To download ExperPort (current name of the behavioral control project), use it, and keep it up to date, you'll need: - '''Matlab''' (We'll assume you have this already. :P ) - any '''cvs...)
(No difference)

Revision as of 17:49, 25 July 2007

To download ExperPort (current name of the behavioral control project), use it, and keep it up to date, you'll need:

- Matlab (We'll assume you have this already. :P )
- any cvs client
- an ssh client (PuTTY used here)
- ... and to contact us later in the process for a username and to register your key


Step 1 - Install PuTTY.

Step 2 - Produce a public/private key pair.

Step 3 - Send us the public key so that we can grant you access.

Step 4 - Create a PuTTY session that uses that key to connect to our server.

Step 5 - Install a CVS client.

Step 6 - Configure your system to use your saved PuTTY session for CVS.

Step 7 - Checkout the ExperPort project.

Step 8 - Run ExperPort!



Step 1: Install PuTTY

  • Install PuTTY to any fixed place by running the install executable or simply downloading the individual executables to the same folder.


It is best to add this folder to the system path for ease of reference. To do so:

  • Click Start, Control Panel, System.
  • Choose the Advanced tab and press the Environment Variables button at the bottom. Select the System variable called Path from the lower window and click Edit. Add a semicolon to the end of the current path string (if there isn't one there already), then type in the path to the PuTTY executables and then OK your way out of the dialogs.



Step 2: Produce a public/private key pair.

  • Run puttygen.exe.
  • Select the SSH-2 DSA radio button at the bottom of the PuTTY Key Generator window.
  • Press the Generate button.
  • Add whatever short key comment you like.
  • You may select a passphrase or elect not to. It is slightly easier not to use one, but if you do not, then anyone with your private key file can log in to our server as you. The cost of using a passphrase is having to double-click your private key file and enter the passphrase each time you start the computer.
  • Pick a nice safe place (Not in code or data directories!) to save both your public and private keys.



Step 3: Send us the public key so that we can grant you access to the server.

  • Email me Saml.gif the public key file you saved (or its contents - it's text). I'll respond when your key is ready to be used - but you can continue through this guide meanwhile.



Step 4: Create a PuTTY session that uses that key to connect to our server.

  • Run putty.exe

The PuTTY dialog windows have changed slightly over time, but for the current version as of 2007.July.25:


In the Sessions option group (initially displayed):

  • Enter the following Host Name: brodylab.princeton.edu
  • Select SSH as the connection type (Port should be set to 22).


In the Connection: Data options subgroup (in the tree on the left):

  • Type in the username you received from us in the Auto-login username field.


In the Connection: SSH options subgroup (in the tree on the left):

  • Select "2" as your Preferred SSH protocol version.


In the Connection: SSH: Auth options subgroup (in the tree on the left):

  • Enter the location of the private key you created (whose corresponding public key you sent to us).


Back in the Sessions options group (top of the tree on the left):

  • Choose a name for the session we've created (like brodylab) in the edit field below the text "Saved Sessions". DO NOT USE SPACES OR SPECIAL CHARACTERS; other programs may not treat them properly.
  • Click Save.


Now your connection is set up and you can double-click it in the list of sessions to test it.

Note that:

- If you haven't confirmed your key with us yet, login will ask for a password (and PuTTY may report that your key has been rejected by the server).

- If you have chosen a passphrase for your key, you need to double-click your private key file (I suggest a shortcut on the desktop.) and enter your passphrase once each time your computer is started to start PAgeant - or else you would have to enter your passphrase on every CVS command!



Step 5: Install a CVS client if you do not already have one.

Which you use will not matter for our configuration.

TortoiseCVS and WinCVS are popular.

- http://www.tortoisecvs.org/

- http://www.wincvs.org/

  • Make sure that the directory that the "cvs" executable is in is in the system path once the program is installed, using the same procedure as above for PuTTY. It may automatically be placed there for you.



Step 6: Configure your system to use your saved PuTTY session for CVS.

The *easiest* way to instruct all cvs clients to use your saved PuTTY session is to define the environment variables CVS_RSH and CVSROOT.

CVS clients will check these variables to determine what connections to open. If you need to connect to other repositories for other applications, please see this footnote* on how CVS selects a connection.


To define these system variables:

- Click Start, Control Panel, System. - Choose the Advanced tab and press the Environment Variables button at the bottom.

- In the lower section, click New. - As the variable name, enter: CVSROOT - As the variable value, enter: <puttysession>:/cvs

    where <puttysession> is the name you gave the putty session we defined above.
    (/cvs is the directory the repository is in on our server.)

- Click OK.

- Click New again (lower section) to enter a second system variable. - As the variable name, enter: CVS_RSH - As the variable value, enter: <PuTTYdirectory>\plink.exe

    where <PuTTYdirectory> is the directory in which you have installed the putty executables.
    If you added that directory to the system path, you can just type:   plink.exe

- Click OK.

Note that environment variables are loaded for a shell/program when it starts, so you'll have to e.g. open a new command prompt (or close and reopen WinCVS) for these variables to be usable there.

At this point, if your username and key are confirmed with us, you should be good to go, with whatever cvs client you use, on the command line, through explorer, or in a big, ugly GUI. :D




Step 7: Checkout the ExperPort project.

  • Pick or create a working directory in which to house the ExperPort project directory. We use C:\ratter.

How to check out the ExperPort project using a GUI varies slightly based on your cvs software (though it should be straightforward); however, you can always just use the command line. (Click Start, then Run, then type cmd and hit enter.)

Command line instructions:

  • Click the Start button, then click Run, then type cmd in the dialog box and hit enter.
  • cd to the directory created (e.g. cd c:\ratter)
  • Type: cvs checkout ExperPort


((Todo: add troubleshooting for the potential problems at this stage.))




Step 8: Run ExperPort!

((Documentation here diverges based on the system that will be used, and will be provided later. Users of the older system should not need to do things any differently.))



Footnote on how CVS selects a connection:

There are several ways to tell CVS what connection to open, and the order will be important to you if you intend to connect to other cvs repositories, too:

1- The -d argument in a cvs command (e.g. cvs -d :ext:user@server.edu:/repository_dir add somefile.txt), if specified, always determines the connection.

2- If there is no -d flag, but there is a "CVS" directory in the directory cvs is called from (i.e. if you are inside a project you've checked out with cvs and type, for example, cvs update), the same connection is used that was used to check out the project.

3- If there is no -d argument and you're not in a CVS working directory, the variables we defined (CVS_RSH and CVSROOT) are used.

This means that you only *need* to specify the cvs repository for the initial checkout. Any commands you enter from inside the project directories will then already know what connection to use.