Quickstart Guide
Last updated
Last updated
This Quickstart assumes that you are familiar with Jupyter notebooks and Python. After getting set up with the Quickstart, please see additional sections in the training guide for more details.
To provide consistency, we use Python 3 in Jupyter notebooks. We also recommend using other standardized approaches as outlined in the Best Practices for Code Development section.
It is recommended that you develop notebook using , as it is the environment teachers and students will use to run these notebooks.
We recommend setting up SSH authentication for interacting with GitHub. To do so, create a new private key on hub.callysto.ca and add the corresponding public key to your GitHub account as per the following instructions.
Using your GitHub email, open a terminal and create the key using the following command and hitting enter when prompted.
Note that by default, the new key will overwrite any key stored in .ssh/id_rsa, so don't accept the default path unless you either have no key stored here or no longer need the original private key file.
Copy the contents of your public key. This is easiest done by opening a new Jupyter notebook and copying the output of the following (the notebook will make it easier to copy and paste the key)
Add the public key to your GitHub account at
There are other options for interacting with GitHub as well. Please see for more information.
You also need to clone the github repo in the directory you are working. From a terminal on a *nix system, that can look like the following:
The options we've added to the docker run command do the following:
-it adds some terminal "niceness",
-p 8888:8888 gives access to the default port (8888),
-v "${PWD}":/home/jupyter shares the file contents with the server,
--name callysto names the container "callysto",
-d "detaches" the container and lets us use the terminal,
--rm removes the container after quitting (lets us re-use the callysto name in other runs).
The port mapping may need to be adjusted if other jupyter servers are running on your machine. The last 3 options itemized above can safely be omitted if you are comfortable managing docker containers, however, the port and volume mapping must always be included.
Following successful launch of the container, navigating to localhost:8888 or using the address+token from the logs will start Jupyter in the web browser as expected. Changes to the files will be synced between the container and the directory where the repository was cloned.
If using this to develop and work with git branches, care should be taken that resources used do not exceed those available on the Callysto Hub: 1GB disk space, 2 GB RAM). Disk usage can be checked using, e.g., du -sh curriculum-notebooks and cannot exceed 1GB for usage on the Hub. RAM usage can be limited by adding a -m 2G to the docker run command.
JIRA is an issue tracking product that provides bug tracking, issue tracking, and project management functions. If your team is using JIRA, follow these steps to access it for the first time:
go to jira.cybera.ca
click on the "Can't access your account?" link
in the "Enter your username" field, enter your EMAIL ADDRESS and click "Send"
check your email for password reset instructions
Remember to Restart and clear output then Shutdown your notebooks before committing your work. This will avoid any odd Git issues that result from some of the git with Jupyter Notebooks issues mentioned above.
If you are new GitHub, here are a couple of guides to get started.
It may be necessary or convenient to be able to run examples or develop on a local copy on your computer/laptop. This might be because you expect to be working without internet access, or working with complex git branches. Jupyter is easy to run after pip installing it, but it is best to match the entire environment (libraries, os, python version, etc.) as the Callysto Hub. The docker images used are hosted on the and uses the image. This does require first.
Jupyter notebooks are written in a JSON format that, when altered using the notebook interface, result in a very difficult to read git diff output. This is because when you change the contents of a given cell, it will have a downstream effect on the notebook's source code, metadata, and output files. At first you may know where to look based on your memory, but when trying to untangle a old notebook's commit history based on git diff there will be difficulties. For this reason it is recommended that you use a tool that makes code comparisons between versions more readable. Please see article for more details.
This assumes that your account was already added to JIRA. If not, please contact your team leader or someone on the .
Please see the and sections for more details. Some examples of Callysto curriculum module notebooks can be found in this .
Once a notebook or other content has been developed, files should be pushed to a off of the master repository.
More with good explanations
Slack is the messaging system used to communicate with the entire Callysto team. If you have not joined the yet, contact your team leader to get added.