Lab 2: Getting Started with TurboGears

Due:  Tuesday, September 18, office hours or by appointment (see turning in your work, below).

• Set up your environment so that you can develop with TurboGears on the MathLAN.
• Experiment with some basic TurboGears features.

Collaboration: You may work in teams of 2-3 for this lab. You may discuss the assignment with anyone you wish. You may obtain help from anyone you wish, but you should clearly document that help. You need turn in only one assignment per team.

• Preliminaries: SSH and MySQL
• TurboGears: The 20-minute Wiki tutorial
• Turning in your work

Preliminaries: SSH and MySQL

Before getting started with TurboGears on the MathLAN, you need to have ready access to the MySQL database server which runs on aiken.  In turn, to have ready access to the MySQL database server, you must set up ssh.

Although I encourage you to work in pairs, each student should complete this part of the lab individually so that everyone is set up to use TurboGears.

1. Follow Mr. Stone's instructions for setting up and using OpenSSH on the MathLAN. You will choose a passphrase and create a keypair. 
2. Practice using ssh to connect to aiken.cs.grinnell.edu, our departmental web and database server.
   

3. On the desktop, go to the Gnome menu (it looks like a footprint) and choose Desktop > Preferences > Sessions.  You should now see a dialog box with three tabs. Select the Startup Programs tab and then click the Add button. Type "/usr/bin/ssh-add" (without the quotes) in the text box and click the OK button. Then click the Close button of the Sessions dialog box.
4. Log out. Then log back in. When Gnome starts, you should see a dialog box that asks you to enter your passphrase. Do so.
5. Test that ssh-agent is working properly: Open a terminal window and type "ssh aiken". If all has gone well, it will not ask you to enter your passphrase again.

Congratulations! You now have ssh-agent working. You can ssh from any MathLAN machine to any other without retyping your passphrase.

The next step is to set up SSH tunnelling for MySQL. This will allow programs you run on a MathLAN workstation to connect to the MySQL server on aiken.

6. Open the ~/.bashrc file in your favorite text editor (e.g., vim, emacs, gedit).
7. Add the following lines to the bottom:
   

   # Have 'tunnel-mysql' set up ssh port forwarding for mysql
   alias tunnel-mysql="/usr/bin/ssh -v -N -L 3306:127.0.0.1:3306 aiken"

   To explain: You are creating up a new command, tunnel-mysql. This command tells ssh to connect to aiken with verbose output (-v), to not execute any remote command (-N), and to set up port forwarding (-L port:host:hostport).  In this case, we forward the default mysql port (3306) on the local host to the the same port on aiken.
8. Save and close ~/.bashrc, then type "source ~/.bashrc" to execute the commands it contains.
9. Type "tunnel-mysql" to start the ssh tunnel.
10. Open another terminal window (or a new tab) and type "mysql -h 127.0.0.1 -u <username> -p <database>", filling in the username and database name you were given by Mr. Stone. When you are prompted to do so, enter the MySQL password you were given by Mr. Stone.  You should see something like the following:
    

    [10:26am] davisjan@rolle (~): mysql -h 127.0.0.1 -u davisjan -p davisjan_sandbox
    Enter password:
    Welcome to the MySQL monitor. Commands end with ; or \g.
    Your MySQL connection id is 9608
    Server version: 4.0.24_Debian-10-log
    
    Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
    
    mysql>

    Type exit to quit mysql.

Congratulations! You have successfully connected to the MySQL server.

In the future, you will need to run the "tunnel-mysql" command in a separate terminal window whenever you run TurboGears.

TurboGears: The 20-minute Wiki tutorial

Whew! Now you have your MySQL tunnel running and you can finally start using TurboGears.

Go to the 20-minute Wiki tutorial and follow the instructions through to the end (pages 1-6). You may work in teams of 2-3. 

Despite the name, this tutorial can take quite a bit longer than 20 minutes, especially if you explore the links. You'll finish the tutorial as homework due next Tuesday.

Some notes and advice on the tutorial...

Page 1:

• Since TurboGears is already installed on the MathLAN, you can skip over "Setting Up," straight to "The Quickstart."

• Since we are using MySQL as our database, you will need to follow the instructions under "Pointing to a Database" to change the database TurboGears uses from sqlite to MySQL. Uncomment the sqlobject.dburi line for MySQL by deleting the octothorpe (#). In this line, replace username, password, and databasename with the information you were given by Mr. Stone. Replace hostname with 127.0.0.1, and use 3306 for the port. You'll also need to comment out the sqlobject.dburi line for sqlite.
• SQL ("Structured Query Language", but everyone just calls it SQL) is a language for storing and retrieving data in databases such as MySQL. We'll learn some SQL later in the semester; you don't need to know much just to get started.

• If you get an ExpatError while loading a page, the ExpatError comes from the XML parser. This means something is wrong in one of your templates. For example, you might have left out a quotation mark. Or, you might forget a closing </div> tag, like I did.
• If you get a "Server not found" error, this probably means that the TurboGears server is not running. TurboGears will automatically shut down if it finds a syntax error in your Python code. You should fix the syntax error and then restart TurboGears.

• Regular expressions (a.k.a., "regexp", "regex", "re") are a very powerful tool for parsing and manipulating text. The regex used to find WikiWords breaks down as follows:
  

  \b([A-Z]\w+[A-Z]+\w+)
  \b			this pattern must be at a "word boundary" (here, the beginning of a word)
     [A-Z] 		matches any single uppercase letter
          \w+ 		matches one or more "word" characters (alphanumeric or underscore "_")
             [A-Z]+ 	matches one or more uppercase letters
                   \w+ 	matches one or more "word" characters
    (     . . .       )	parentheses indicate that all these characters are to be grouped together 
  			into a single word (or "token", in the parlance of regexes)

  We'll learn more about how to use regular expressions later in the semester. You'll learn how they work when you take Automata (CSC 341).

• If you get to the end of the tutorial and your AJAX doesn't work as advertised, there may be a syntax error in the JavaScript. Luckily, FireFox/IceWeasel has a tool to help diagnose such errors. Go to the Tools menu and select Error Console. You will see a list of errors. Click on the hyperlink to view the page source with the error highlighted in context.
• Unfortunately, TurboGears doesn't reliably react to changes to the master.kid file. If you don't see your changes to master.kid (including bug fixes), try stopping and restarting the TurboGears server.

When you are done, quit the TurboGears server and the MySQL tunnel.

If you haven't done so already, read about The Big Picture. Feel free to email me with any questions.

Turning in your work

Come show me what you did! Sign up for a 15-minute office hour slot on Tuesday, September 18. If you can't come to my office hours, make an appointment with me for some other time this week. If you worked in a team, plan to all meet with me together.

I'll ask you how it went, you'll give me a demo of your Wiki, and you'll have a chance to ask me any questions you have about TurboGears.

Janet Davis (davisjan@cs.grinnell.edu)