Home
Getting Started with CACAO¶
Requesting an allocation on Jetstream-2
Logging into CACAO¶
Click here: https://cacao.jetstream-cloud.org/ URL
CACAO uses ACCESS-CI CILogon with DuoAuth
Setting up DuoAuth Multi-Factor Identity
You should now see the CACAO homepage
Creating Credentials¶
Before you can use Jetstream2 you need to create credentials for your user profile.
Select the + Add Credential button in the upper right of the panel
Select the Cloud Credential option and select Jetstream 2
Select any of the Jetstream2 Cloud Projects that you have access to (it may be only one project if this is your first time)
You should now see a completed summary with success:
Optionally, you can also create a Public SSH Key for yourself.
SSH keys are a good way to secure your deployments
Create a New Deployment¶
CACAO uses the concept of Deployments for new projects
Select the Deployments tab on the left side:
Click the + Add Deployment button
Select the launch a multi-vm zero-to-jupyterhub template
Create a new Jupyter Hub¶
Step 1: Set the Region to launch your Jupyter Hub¶
Currently, CACAO only supports the Jetstream2 IU cloud
The only region available to you in Jetstream2 is the Indiana University (IU)
You may create Credentials in the future with different cloud providers (Commercial or OpenStack)
Step 2: Set the Parameters¶
Give your deployment a name. This is the name that will show up on the command line, so keep it short and without spaces
Under the advanced options, you can disable access to the master node. Do this if you anticipate a lot of activity across the Hub or by users which max the CPUs and might cause problems managing the cluster.
Custom Domain Names
You can set up a DNS redirect to your custom website URL. In order to do this, you must set up a permanent IP address which your DNS recognizes.
Step 3: Set up Authentication¶
There are two types of user authentication
Dummy Authentication allows you to create new user names and dummy passwords
GitHub Authentication is a multi-step process
Setting up GitHub Authentication
Step 1: Click on User Account Settings
Step 2: In the left sidebar at the very bottom, click Developer settings
Step 3: In the left sidebar, click OAuth Apps and select New OAuth App
Step 4: Create and register your new application
Step 5: Create a client secret
Step 6: Copy both the Client ID and Client Secret to the Auth template
Step 7: Set the Authorization Callback URL -- if you're using a custom DNS, type that here. If you're using a basic IP Address use it here.
Step 4: Set up Users¶
The JupyterHub users can be created at this time.
Important: you must have an administrative user account
Make sure to create at least one user with "admin" privileges at this time
You can create more accounts later on, so if you're in a hurry you only need one admin before launching the Hub.
More admins and users can be created in the Jupyter Hub Admin panel
Step 5: Set up Shared Storage¶
You can add a Shared Storage volume to your cluster.
You can also choose whether to make this volume "read-only"
Step 6: Select the appropriate Docker Image¶
In this step you're actually selecting a Docker Image from a public registry
We recommend you use a featured Project Jupyter Docker Stack image, or one of ours:
harbor.cyverse.org/rstudio/binder:latest
harbor.cyverse.org/jupyter/minimal:latest
harbor.cyverse.org/jupyter/datascience:latest
Step 7: Review and deploy ¶
You can see all of your choices for the cluster at this time. Make sure they are to your liking then click Submit
Hubs typically take 8-16 minutes to provision before they are fully "Active"
Log into JupyterHub for the first time as Admin¶
Login to the master mode running the Hub by copying the IP address and pasting it in your browser.
The Hub will ask for you to login. Enter the username and password you set up in Step 3 and Step 4.
The cluster will start up a new instance for your account
You will be taken directly to a JupyterLab instance on the cluster
To access the Admin Panel, you can enter a different path in the URL: http://<IPADDRESS>/hub/admin
As the admin, you can add other admins or user accounts. These will all use the same Dummy Password set up in Step 3, unless you chose the option for GitHub Authentication. For Github all new usernames must be validated GitHub accounts. Those users must sign in with their GitHub authentication.