Unpacking your Whale in a Box

Prerequisites

Installation

  1. Get the Whale in a Box Kit using one of the following methods:
  2. Open a terminal and change to the Whale in a Box Kit directory.
  3. Create a file to contain secret credentials. Do not check-in this file.

    Bash

    Name the file secrets.sh and add the your Carina credentials:

    export CARINA_USERNAME=username
    export CARINA_APIKEY=apikey

    PowerShell

    Name the file secrets.ps1 and add your Carina credentials:

    $env:CARINA_USERNAME="username"
    $env:CARINA_APIKEY="apikey"
  4. Run the following command to perform one-time setup tasks:

    Bash

    ./setup.sh

    PowerShell

    .\setup.ps1

    Note: You will be prompted to log into Docker Hub. This is how your Jupyter notebooks and materials are distributed to your users.

  5. The output from the previous script includes the IP address of the website. If you have a custom domain name, update your DNS and add an A record pointing to the IP address. Depending on TTL (time to live) settings, this will a few minutes or longer.

    You can determine when the entry is ready by running the following command, replacing example.com with your domain name:

    Bash

    dig +short example.com

    PowerShell

    nslookup example.com
  6. Register the website with Carina OAuth. For the Callback URL use https://<domain-or-ip>/jupyter/hub/oauth_callback.

  7. Add your Carina OAuth credentials to the secrets file.

    Bash

    Edit secrets.sh and add your Carina OAuth credentials:

    export CARINA_OAUTH_CLIENT_ID=application-id
    export CARINA_OAUTH_CLIENT_SECRET=secret

    PowerShell

    Edit secrets.ps1 and add your Carina OAuth credentials:

    $env:CARINA_OAUTH_CLIENT_ID="application-id"
    $env:CARINA_OAUTH_CLIENT_SECRET="secret"
  8. Customize the settings file by following the directions in the file. If you are using PowerShell, edit settings.ps1, otherwise settings.sh.
  9. Run the following command to create the website. This command can be rerun at any time to update the website assets, materials, or just fix things if they break.

    Bash

    ./run.sh

    PowerShell

    .\run.ps1

Customize

This is a mighty fine boxed whale, ready to be taken home and turned into your very own howtowhale. Most things can be tweaked without having to delve into the deployment infrastructure.

Materials

Add Jupyter notebooks and other materials to the materials directory and redeploy.

Landing Page

Edit html/index.html and redeploy.

User Jupyter Server

Edit Dockerfile-jupyter where you can change the base Jupyter notebook server image or install dependencies.