* Set STOPWIKIWORDLINK = JupyterHub

This provides information on using Flatiron Institute's Binder Jupyter notebook interface.

See External BinderHub for how to set up these sharing environments.

Background

To use the Binder service (or west-coast SDSC Binder), you must be sent a link by a Flatiron Institute researcher to their shared environment. This service uses BinderHub, which is a tool to dynamically build and Jupyter environments.

Usage

First, you should either follow the binder link or enter the owner (Flatiron user) and project name sent to you by a Flatiron Institute researcher to access an environment.

Logging in

You will be prompted to log in with a Google account. Any account will work, but the link you were set may only work for the account it was sent to. If you get an access denied error, please check with the Flatiron Institute researcher. (If you do not have or want a Google account, please contact us.)

You may be prompted with two "Authorize access" pages: one from Google to grant access to Flatiron JupyterHub, and one from JupyterHub to authorize you to Binder. Please accept both.

Building

Once you get to the binder page you can build the environment. This may take some time the first time it's used. You can click on "show logs" to watch the progress. Be sure to stop any running server before building a new environment.

Updating the environment

If the environment itself is ever updated by the Flatiron researcher and you wish to access the new version, you must stop the server and then return to the top page to re-enter the environment name, rather than just restarting the server. Restarting the server from the JupyterHub page will always re-use the last version you ran.

Launching the Server

Once the environment is built, it will launch the server. Each user may only run one server at a time, so you must stop any running server before starting another one, even if it's from a different project. If you get an error that you already have a running server, visit the JupyterHub page to reconnect to or stop your current server. If you get an error about taking too long to launch, it may be that there are no free resources at the moment, in which case you can try again later.

Using the Server

You can find information on using the server itself in the Jupyter classic and JupyterLab documentation, depending on which environment the project uses.

The environment, packages, files, and data available depend on the particular environment specified by the Flatiron Institute researcher.

Resources

By default, each server has 1 (one) CPU core and 10GB of memory available for processing, but this can be configured by the Flatiron researcher in the project environment. Using more memory than this may result in the server being shut down.

Storage

Most environments will contain a folder called "home" which stores your personal files, and is maintained between servers and projects. Any files you save or modify outside of this directory will be lost as soon as the server is shut down. Be sure to store anything you want to keep for a few days in this directory.

We ask that users limit data on binder to 1TB at most.

Do not store any sensitive or critical data on this service. Anything you put in your "home" directory may be made available to Flatiron Institute researchers for the purpose of collaboration.

All storage and resources should be considered best-effort scratch space and come with no guarantees or backups. Your entire account, including files in your "home" directory will be removed after 7 days of inactivity.

Downloading data

The easiest way to download data is though Jupyter's file tree browser, which is the default page you see when you first open a regular binder. Click on the checkboxes next to the files you want to download, then click the Download button that appears.

If you are running JupyterLab inside your binder, you can similarly right-click on files in the JupyterLab file browser to get a download link.

If you have many files, or a directory of files, you might want to use tar or zip to create a single archive file that you can download. Some environments may have additional plugins that help with this.

You can also use the Jupyter terminal to run scp or rsync, if they are installed in the environment. For example, you can run:

rsync -a home/mydir/ youruser@remote.server.edu:mydir

To copy data from your home to another server. This must be a server on the internet that you can already ssh to.

Support

For any issues that arise connecting to, building, or using a Jupyter environment, including the kernel, python packages, and shared data, contact the Flatiron Institute researcher who provided the project link. For issues with the website itself, problems logging on, or errors related to its use, contact scicomp@flatironinstitute.org.

These resources are made available to external researchers for approved research uses only on a best-effort basis. Servers may be stopped, data may be removed, or access may be revoked for any reason at any time.

Maintenance Schedule

Binder maintenance and upgrades may be done on Monday mornings, 9am-noon ET. This will usually only be done every few months, and notices will be given on the launch and hub control panel page.