# code.mindmeldr.com /graphterm

### Navigation

- index
- next |
- previous |
- Docs Home |
- Contents »

# Getting started

Contents

- Getting started
  - Running GraphTerm
    - iPad/Android tablet usage
  - Inline graphics and notebook mode
    - Inline plots using matplotlib
    - Inline tables using pandas
    - Notebook mode
  - Sharing and security
    - Terminal sessions and “screensharing”
    - Security

## Running GraphTerm

To install `GraphTerm`, you need to have Python 2.6+ and the Bash shell on your Mac/Linux/Unix computer. For a quick install, use one of the following two options:

    sudo pip install graphterm
         OR
    sudo easy_install graphterm; sudo gterm_setup

Omit the `sudo` if you are installing as a non-root user within an Anaconda or Enthought Python environment, for example. (See the Installation section of the README file for additional installation options, including source installs.)

To start the `GraphTerm` server, use the command:

    gtermserver --terminal --auth_type=none

This will run the server and open a GraphTerm terminal window using the default browser. For multi-user computers, omit the `--auth_type=none` option when starting the server, and enter the authentication code stored in the file `~/.graphterm/_gterm_auth.txt` as needed.

You can access the GraphTerm server using any browser that supports websockets. Google Chrome works best, but Firefox, Safari, or IE10 are also supported. Start by entering the following URL:

    http://localhost:8900

In the `graphterm` browser page, select the GraphTerm host you wish to connect to and create a new terminal session. (Note: The GraphTerm host is different from the network hostname for the server.) Within a GraphTerm window, you can use terminal/new menu option to create a new GraphTerm session.

You can also open additional GraphTerm terminal windows using the `gterm` command:

    gterm --noauth [session_name]
    gterm -u ubuntu --browser="Google Chrome" https://example.com:8900

where the terminal session name argument is optional. (This command can automatically process authentication codes from your `~/.graphterm` directory.)

Type `gtermserver -h` to view all options for starting the server. You can use the `--daemon=start` option to run the server in the background. The `--host=hostname` option is useful for listening on a public IP address instead of the default `localhost`. The `--auth_type=none` no authentication mode is useful for teaching or demonstration purposes, or on a single-user lapttop/desktop, where security is not important. Another useful no authentication mode is `--auth_type=name` which enables simple name-based sharing. (For more on running publicly accessible GraphTerm servers, see Setting up a Virtual Computer Lab.)

Within the terminal, try out the following commands:

    hello_gterm.sh
    gls <directory>
    gvi <text-filename>

The `gls` and `gvi` commands in the GraphTerm toolchain imitate basic features of the standard `ls` and `vi` commands (see GraphTerm toolchain and features). (Note: You need to execute the `gterm_setup` command to be able to use the GraphTerm toolchain. Otherwise, you will encounter a `Permission denied` error.) To display images as thumbnails, use the `gls -i ...` command. Use the `-h` option to display help information for these commands, and read the tutorial Using the graphical features of GraphTerm for usage examples.

If you wish to use GraphTerm to set up up a virtual computer lab for multiple users, see the section Setting up a Virtual Computer Lab. To use GraphTerm features on remote systems and via SSH, see Remote access and SSH.

### iPad/Android tablet usage

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. (The Footer menu display can also be toggled by clicking on the last displayed prompt.)

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

## Inline graphics and notebook mode

GraphTerm supports inline graphics display with `matplotlib` and `pandas` Python packages (see below) and also with R (see Using GraphTerm with R). It also supports a lightweight notebook interface.

### Inline plots using matplotlib

Assuming you have `matplotlib` installed, the `gpylab` module in the `$GTERM_DIR/bin` directory can be used to start up the python interpreter in `pylab` mode for inline graphics within the GraphTerm terminal:

    python -i $GTERM_DIR/bin/gpylab.py
    >>> plot([1,2,4])
    >>> plot([1,3,9])     # Overplot
    >>> figure()          # Clear figure
    >>> plot([1,3,9])
    >>> newfig()          # New figure
    >>> plot([1,4,12])

Inline graphics also works with the `ipython` command in a similar manner. Instead of typing the long python command line above, you can use the shortcut commands `gpython` or `gipython`, e.g.:

    gpython
    >>> plot([1,2], [3,6])

Run `$GTERM_DIR/bin/gmatplot.py` for a demo of inline graphics (see Simple inline animation using matplotlib). See the function `main` in this file for sample plotting code.

> - Use `figure(...)` to clear current image
> - Use `newfig(...)` to create blank image
> - Use `resize_newfig(...)` to create resize blank image
> - Use `show()` to update image
> - Use `show(False)` to display as new image
> - Use `display(fig)` to display figure
> - Use `ioff()` to disable interactive mode
> - Use `gterm.nbmode(False)` to re-enable default expression printing behaviour

### Inline tables using pandas

GraphTerm can display `pandas` DataFrame objects as a table using HTML:

    gpython
    >>> import pandas as pd
    >>> d = {'one' : [1., 2., 3., 4.],
    >>> 'two' : [4., 3., 2., 1.]}
    >>> pd.DataFrame(d)

### Notebook mode

GraphTerm supports a notebook mode, where code can be entered in multiple cells and executed separately in each cell to display the output (see GraphTerm Notebook mode running Python). Currently, the notebook mode can be used with the shell (`bash`), or while running python (`python/ipython`) and `R` interpreters (see Using GraphTerm with R). You can create new notebooks using the notebook/new menu option and then selecting the language.

You can try using the notebook mode with any other shell-like program (such as `IDL` or `ncl`) which has a unique prompt by typing Shift-Enter after starting the program. Type Control-Enter instead, if you wish to read a notebook file and/or customize the interpreter prompts. Alternatively, you can select notebook/new/default menu option after starting the program (this works even with the `bash` shell!).

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. Alternatively, you can use the `gpython` or `gopen` commands python notebooks:

    gpython notebook.ipynb

For other languages, you will need to start the interpreter and then use the notebook/open menu option.

Within notebook mode, 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.

Notebook cells can also contain descriptive text in Markdown format. The notebook/markdown menu option can be used to toggle a cell between code and Markdown mode and double-clicking on the rendered text displays the editable Markdown cell.

The notebook/save menu option can be used to save notebooks either in the IPython Notebook format (`*.ipynb`) or in the Markdown notebook format (`*.py.gnb.md`). The filename determines which format is used. You can exit the notebook mode using notebook/quit in the top menu bar, or by typing Control-C, to return to the terminal mode.

## Sharing and security

### Terminal sessions and “screensharing”

For each host, terminal sessions are assigned default names like `tty1`, `tty2` etc. You can also create unique terminal session names simply by using it in an URL, e.g.:

    http://localhost:8900/local/mysession

The first user to create a session “owns” it, and can make the session publicly available by disabling the share/private menubar option. The public session URL can then be shared with other users connected to the same GraphTerm server, to provide read-only access to the terminal. (This is like “screensharing”, but more efficient, because only the content is shared, not the theme/style data.)

If the session owner has unlocked the session by disabling the share/lock menubar option, other users can also steal control of the session using the menubar button (or using the share/control menu item).

For example, if you forgot to detach your session at work, you can `ssh` to your desktop from home, use SSH port forwarding to securely access your work desktop, and then steal the session using your home browser (see Remote access and SSH).

Normally, only a single user has control of a terminal session at a time. There is a share/tandem option that can be enabled to allow multiple users to control the terminal session at the same time. However, this could sometimes have unpredictable effects.

### Security

You should normally run GraphTerm logged in as a regular user, using the default `--auth_type=singleuser` option, which requires an access code for HMAC authentication. Using the `gterm` command to create a new terminal provides convenience and additional security, as the command validates the server and handles authentication before opening a new terminal. On a single user computer, such as a laptop, the `--auth_type=none` option, with no access code, can be used instead.

Although GraphTerm can be run as a public server, this feature is best used for teaching and demonstration purposes. In this case, the `--auth_type=name` option can be used, if all users can share an account, with no access code. The `--auth_type=multiuser` option, which requires the server to run with root privileges, is suitable for a multiple user lab setting, providing a choice of either access code HMAC authentication or Google Authentication. The `--auth_type=login` option, which is permitted only with a localhost server or with HTTPS, implements the standard password login. The `--nolocal` option can be used to disable root access via the browser. The HTTPS protocol can be enabled for the public server, using either self-signed or authoritative certificates, to provide additional security. (See see Setting up a Virtual Computer Lab for more on authentication options.)

When working with sensitive information, it would be best to run the server on `localhost` (the default) and use SSH port forwarding to connect to it from other computers as needed (see Remote access and SSH).

### Navigation

- index
- next |
- previous |
- Docs Home |
- Contents »