Using the GraphTerm Virtual Computer Lab

Logging in

Open the URL provided by the instructor (usually of the form http://hostname.domain) in your web browser. (Google Chrome works best, but Firefox, Safari, or IE10 would also work.) Then type in the user name and the access code. If you are creating a new account, you will need to enter the group access code obtained from your instructor. Select a user name that will be meaningful to the instructor, like your first initial followed by your last name (all lower-case), e.g., jsmith for Jim Smith. If you have a Google GMail account, you can choose to link it to your GraphTerm server account for password-less logins by clicking the Google Auth button. (You will still need to enter the group access code the very first time to create your new account and link it to your GMail account.)

https://github.com/mitotic/graphterm/raw/master/doc-images/gt-login.png

Note: If the URL is of the https//... form, you may encounter warning messages about untrusted certificates, and be asked to make an exception. The instructor may ask you to ignore these warnings and accept the certificate, if the GraphTerm server has been configured to use a self-signed certificate. Also, self-signed certificates do not work with Safari on the Mac; use Chrome or Firefox instead.

https://github.com/mitotic/graphterm/raw/master/doc-images/gt-new-acct.png

If you just created a new user account, note down your user name and personal access code, as you will need it for logging in later (unless you are using Google Authentication). You may optionally enter your email address at this point. If you forget your personal access code, the instructor can retrieve it for you.

If you have a Mac/Linux desktop/laptop, you can download the executable python script $GTERM_DIR/bin/gterm.py and type the following command on your desktop/laptop:

gterm.py -u user http://hostname.domain

to open a terminal on the remote server without having to type in the access code (after the first time).

On Windows: The Google Chrome and Firefox browsers work best, but Internet Explorer 10 should also be usable, with some limitations.

Creating and leaving terminal sessions

https://github.com/mitotic/graphterm/raw/master/doc-images/gt-host-list.png

After logging in, choose the host that has the same name as your user name, and then you can connect to an existing terminal session or create a new terminal session. You can choose a specific name for a new terminal session, or type the special name new to automatically choose names like tty1, tty2 etc. You can also create new terminals as needed using the terminal/new menu option.

https://github.com/mitotic/graphterm/raw/master/doc-images/gt-create-session.png

You can type standard Unix commands, like cd, ls, cp etc. in the terminal. The command menu lists some commonly used commands. Often, it is preferable to use the GraphTerm-aware gls command, instead of the standard ls command, as it allows you to navigate directories by clicking.

https://github.com/mitotic/graphterm/raw/master/doc-images/gt-new-session.png

To leave a terminal session, use the terminal/detach option, which will return you to the list of terminals. Detaching a terminal still keeps it alive, and you connect to it at a later time, without losing its state. For example, you can create a terminal at work, and later connect to it from home.

Troubleshooting

If the terminal is unresponsive (i.e., appears to “hang”), try one or more of the following:

  • Do what you would normally do in a Unix terminal, type Control-C to interrupt the currently running program. You can also use the command/interrupt menu option instead.
  • If you are in the fullscreen graphics mode (e.g., using gframe), you may need to click on the top of the terminal portion of the window to get the input focus out of the embedded frame and then type Control-C. You can also try the command/parent interrupt menu option to interrupt the currently running program in the parent window.
  • Are you in the notebook mode? If so, the notebook name will appear on the top, with the prefix “NB”. To exit the notebook mode, use the notebook/quit menu option, or type Control-C and then type Control-D to exit the python interpreter. (Remember to save the notebook before exiting, if necessary.)
  • Use the terminal/reload menu option or the browser’s reload button to reload the web page. Copy/paste any displayed code in notebook cells before reloading, as you may lose it.

Sharing terminal sessions

If your instructor has enabled sharing for all, or created sharing groups, you can view and control terminals belonging to other users, who will appear as additional hosts.

You can watch someone else’s terminal, without controlling it, simply by selecting a different host from the list. You can also steal control of someone else’s terminal, if the terminal owner has previously unchecked the share/locked menu option. (To regain control, the terminal owner would have to steal it back.)

Chatting: Using the command/chat option, you can enable chat communication between all watchers for a terminal session. The command needs to be invoked at the shell prompt, before running the python interpreter or opening a notebook, and it displays a chat button near the top right corner. When chatting, an alert button also becomes available to attract the attention of the watchers (which may include the instructor).

There is also an experimental option for unlocked terminals, share/tandem, which allows two people to control a terminal simultaneously. However, sometimes this can lead to unpredictable results, due to the time lags between terminal operations by multiple users.

Pasting text into the terminal

To paste copied text into the terminal, click on the red cursor and then use the standard paste command on your computer (Command-V on the Mac and Control-V on other systems). If the keyboard command does not work, you can try the terminal/paste special menu option.

GraphTerm Notebook interface

Two ways to use the notebook interface are supported in the virtual computer lab:

1. Using the lightweight Notebook mode built into the remote GraphTerm terminal.

2. Running the IPython Notebook server on the remote computer and accessing it using a browser on your local computer (see next section for detailed instructions).

The GraphTerm notebook interface is implemented as a wrapper on top of the standard python command line interface. It provides basic notebook functionality, but is not a full-featured environment like IPython Notebook. It does support the same notebook format, which means that you can create simple notebooks in GraphTerm, save them as .ipynb files and open them later using IPython Notebook, and vice versa. The GraphTerm notebook interface is integrated into the terminal, which allow seamless switching between the python command line and notebook mode, as well as “live sharing” of notebooks across shared terminals.

Running IPython Notebook server

To access the full features of the IPython Notebook, you can run your own password-protected public IPython Notebook server on the remote machine using the gnbserver command (if the instructor has enabled this option). You can then access it using your local browser, with an URL of the form https://hostname.domain:port, where port is the port number output by the gnbserver command. The notebook password is the same as the access code for your user account. (Note: Run the gnbserver command in a separate terminal window.)

Once the server is running, individual notebook files can be opened in the IPython Notebook server using the gipynb command:

gipynb notebook.ipynb

or by simply clicking on the .ipynb file in the gls output listing.

Note: If each user is running their own copy of the IPython Notebook server, it can degrade performance on a shared computer. Please consider shutting down the server when you are not using it.

Opening Python notebooks in GraphTerm

To open a new python notebook, use the menu command notebook/new/pylab

To open an existing notebook, use the gls command to list your notebooks, e,g.:

gls *.ipynb

Then click on the notebook that you wish to open. This will open the notebook using the IPython Notebook server, if it is running, or using the GraphTerm notebook mode otherwise. Alternatively, you can also use the gopen command:

gopen notebook.ipynb

To open notebook files using the built-in GraphTerm notebook mode, you can use the gpython or gipython command:

gpython notebook.ipynb

or simply run the standard python command and type Shift-Enter to enter the notebook mode as needed.

https://github.com/mitotic/graphterm/raw/master/doc-images/gt-nb.png

Once you have opened a notebook, you can enter code in the notebook cells. Type either Control-Enter to execute code in-place, or Shift-Enter to execute and move to the next cell (creating a new cell, if necessary). You can also use the run button on the top menu, which behaves like Shift-Enter but does not create new cells. Other notebook operations can be carried out using the notebook menu or the keyboard shortcuts listed under help/notebook shortcuts.

Saving and exiting python notebooks

IPython Notebook server has a menu option to save notebooks. To exit the notebook, click the red X in the top left corner.

To save a GraphTerm mode notebook, use the menu command notebook/save. To exit the GraphTerm notebook mode, you can simply type Control-C or use the notebook/quit menu option. This returns you to the python command line, with the chevron (>>>) prompt.

To exit the python command line, type Control-D or the following command:

>>> exit()

Downloading files

To download files, use the gdownload command:

gdownload filename(s)

Right-click (or control-click) on the displayed link to download. On some browsers, like Chrome, directly clicking on the link would also work. If more than one file (or a directory) is specified for downloading, the command automatically creates a zip archive. This works well for archive sizes of 1-2 MB, but for larger archives, you should create the archive yourself using the zip command and then download the single archive file.

You can also download multiple files, one-at-a-time, using the following command:

gls --download filenames

Click on the displayed filenames to download.

Note: Browsers other than Chrome typically append .html or .htm to the downloaded filename. For example, file abc.ipynb may be downloaded as abc.ipynb.html. If needed, you can rename the downloaded file by gently clicking on the name in the Finder window and deleting the .html extension.

Uploading files

Use the gupload command to upload files to the remote terminal. First cd to the directory where you want to upload the file and type:

gupload optional_filename

Then select (or drag-and-drop) the file from your local computer. If you do not provide a filename, the original filename will be used. This command works well for file sizes of a few MB, but can be quite slow for larger files.

On Windows: Drag-and-drop for files currently does not work with IE10.

SSH key access

If you have an SSH client on your local computer, upload the public key file (usually id_rsa.pub) using the gupload command as ~/.ssh/authorized_keys to enable SSH access to your account:

ssh username@server_domain

Keyboard shortcuts

The special keystroke Control-J, followed by a sequence of letters, can be used to access all menu commands from the keyboard. The letter to be typed is highlighted and is usually, but not always, the first letter of the menu item to be selected. For example, the key sequence Control-J t c can be used to clear the terminal and the sequence Control-J c i can be used to send a Control-C interrupt.

In notebook mode, several keyboard shortcuts with the prefix Control-m are also available, similar to IPython Notebook. See help/notebook shortcuts menu option for more info.

Windows-specific tips

The Google Chrome and Firefox browsers work best on Windows, but Internet Explorer 10 should also be usable, with some limitations.

The Unix Control-C and Control-D key combinations do not always work as expected in Windows browsers. To send Control-C or Control-D, you can use the menu options, or the keyboard shortcuts prefixed with Control-J.

The up-arrow and down-arrow keys for command recall do not work with IE10.

Tips for Android/iPhone/IPad

GraphTerm can be used on touch devices (phones/tablets), with some limitations. Use the view/footer menu to enter keyboard input, send special characters, access arrow keys etc. Tap the Kbrd in the footer to display the keyboard.

Note: You should turn off the Autocapitalize and Autocorrect features in the language/keyboard settings if you want to do a lot of typing on touch devices.