Documentation

Intro to Telescope for Dummies

This document is an old-school, grass-fed, hand-written documentation to help people get started with self-hosting Telescope and/or contributing to the project. We welcome suggestions and/or contributions, so please contact us with any feedback!

What is Telescope?

Telescope is an open source software for visualizing the status of your jobs on your computing cluster. It uses a secure login protocol, so a password isn't required each time one connects to the cluster. We plan to implement new features, such as htop for real-time monitoring of your nodes, in the future.

Installation process

To install Telescope, you can use either PIP or setup.py.

Using PIP

Simply run on your terminal:

pip install git+https://github.com/QCB-Collaboratory/telescope

Using the setup.py script

1. Clone the Telescope repository. For instance, you can run the following on your terminal:

git clone https://github.com/QCB-Collaboratory/telescope

2. Go to the telescope directory.

cd telescope

3. Run the setup.py install script as root or with sudo (you will be asked to authenticate). Note: Be careful when using sudo.

sudo python setup.py

Running Telescope

To run a self-hosted version of Telescope, you will need the following items.

• Successful installation of Telescope
• Configuration file with credentials to connect the server and list of usernames
• Python script that starts the server (provided in test directory in Telescope repo)
• A running server in the background

Each item is described in detail below.

Configuration file

You need to create a file named config.ini with the following format (copy this block of code into a text editor, and make sure to save with a .ini extension):

[CREDENTIALS]
USER   = <USERNAME>
SERVER = <SERVER ADDRESS>

[MONITOR]
NUMUSERS = 1
USER1 = <USERNAME>

By using the configuration file above, Telescope will attempt to connect to the server by using ssh key pairs. If passwords are necessary, set your password as the second option in the CREDENTIALS group.

Starting a Telescope Server

There is a test directory in the telescope repository that contains a RunTelescope.py script. If Telescope was installed correctly (using PIP or setup.py), then RunTelescope.py should open a web browser with the Telescope interface, provided you have a config file with valid username and server address in the current directory.

Here is a copy of RunTelescope.py:

import telescope

server = telescope.server()
server.run()

If you would like to point Telescope to a specific directory with your config file, you can customize the RunTelescope.py script to reflect the path to your config.ini:

server = telescope.server(config = '/path/to/config.ini' )

Happy Coding!