Unpacking your Whale in a Box



  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.


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

    export CARINA_USERNAME=username
    export CARINA_APIKEY=apikey


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

  4. Run the following command to perform one-time setup tasks:





    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:


    dig +short example.com


    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.


    Edit secrets.sh and add your Carina OAuth credentials:

    export CARINA_OAUTH_CLIENT_ID=application-id


    Edit secrets.ps1 and add your Carina OAuth credentials:

  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.






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.


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.