Unpacking your Whale in a Box

Prerequisites

A Carina account. If you do not already have one, create a free account (no credit card required) by following the sign up process.
Your Carina API key. To get it, go to the Carina Control Panel, click your username in the top-right corner, and then click API Key.

Installation

Get the Whale in a Box Kit using one of the following methods:
- Clone the repository: git clone https://github.com/carolynvs/whaleinabox-kit.git.
- Download https://github.com/carolynvs/whaleinabox-kit/archive/master.zip and unzip it.
Open a terminal and change to the Whale in a Box Kit directory.
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"
```
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.
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
```
Register the website with Carina OAuth. For the Callback URL use https://<domain-or-ip>/jupyter/hub/oauth_callback.
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"
```
Customize the settings file by following the directions in the file. If you are using PowerShell, edit settings.ps1, otherwise settings.sh.
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.

Change FROM jupyter/minimal-notebook to another base Jupyter notebook server of your choice. I recommend selecting one from the Jupyter Docker Stacks project.
Add RUN <command> to install additional dependencies, for example RUN apt-get update && apt-get install -y curl or RUN pip install pandas.