Skip to content
Permalink
main
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

CLASS-Essentials/Build.md

Go to file
 
 
Cannot retrieve contributors at this time
Book Build Instructions Building and Publishing the Book VM Development Setup Google Cloud Google Cloud Shell Development Google Virtual Machine Development AWS Azure Jupyter Book Tags Bugs and Fixes
114 lines (79 sloc) 4.82 KB
Raw Blame
Open in GitHub Desktop

Book Build Instructions

Building and Publishing the Book

All the build scripts must be run from the top of the repository.

To build the book for local development run

./scripts/build-book.sh

This will create a local Python venv environment in .venv/, install Jupyter Book and dependcies and build it. The Jupyter Book content is located in content/. The build process does not reevaluate the Jupyter Notbooks due to the complexity of building across all the providers in a single run. Development for each provider should be done in a branch (gcp-dev, aws-dev and azure-dev branch).

The resulting book is a set of static html pages found in content/_build/html/. If development is being done remotly these pages can be exposed on port 8080 by running.

./scripts/preview-book.html

This runs a local http server enabling the "preview" feature of the Cloud Shell to view the rendered book. Visual Cloud Studio, when used in a remote shell, will also redirect this port to the local developmen machine and the previw can be found on localhost:8080.

To use GitHub pages to preview or publish run

./scripts/push-book.sh

THis will copy rendered content to the gh-pages branch and push to the private remote.

To publish to the gh-pages of the origin (or other) remote run.

./scripts/push-book.sh origin

This copies the contents of content/_build/html/ to docs/ so GitHub Pages will render the document. GitHub pages should be set to the gh-pages and docs/ folder. The script pushes a new branch overwriting the old branch and will not track changes.

VM Development Setup

Have your ~/.ssh/config source the file the *-create.sh scripts create. This is a one-time per machine setup.

echo "include ~/.ssh/essentials.config" >> ~/.ssh/config

Verify your name and email are correct (locally) as they are copied over to the VM

git config user.name
git config user.email

Google Cloud

Google Cloud development is split between the Cloud Shell episodes (04_intro_to_cli and 05_cli_storage) and the VM episodes. Although the Cloud Shell episodes should work on the VM the prompt responses are slightly different.

The Jupyter notebook is forwarded to http://localhost:8080 and the preview on http://localhost:8081. Use the links in the output of the script for Jupyter to login with the proper authentication key.

First setup the Google Cloud SDK and login to the account and project that you are going to use for development.

Verify the active project and account with

gcloud config configurations list

Google Cloud Shell Development

The project is located in a hidden directory (.essentials) to hide the output from Jupyter and the students. To start Cloud Shell run ./scripts/gcp-cloudshell.sh to open the shell with the agent and ports 8081 and 8080 forwarded (Jupyter and preview respectively) and run the following commands to setup the Cloud Shell (this needs to be done only once). Be sure to check the project and account values.

git clone git@github.internet2.edu:/CLASS/CLASS-Essentials.git .essentials
( cd .essentials/ ; git checkout -b gcp-dev --track origin/gcp-dev )

ACCOUNT=learner@class.internet2.edu
PROJECT=essentials-learner
cat > .essentials/local.sh <<EOF
gcloud config set account $ACCOUNT
export GOOGLE_CLOUD_PROJECT=$PROJECT
export DEVSHELL_PROJECT_ID=$PROJECT
gcloud config set project $PROJECT
EOF

Then run the following from your local machine (Make sure to shutdown from the web-gui as ctrl-c is not managed properly):

./scripts/gcp-cloudshell-jupyter-lab.sh

Google Virtual Machine Development

If you manually create a with the instructions in the 06_running_analysis episode you must use the us-west2-c zone or delete it and let the script create it.

Workflow

  • Create and configure a new VM with ./scripts/gcp-create.sh
  • Open Jupiter link shown in the output of the gcp-create.sh script.
  • Delete the vm when done (don't forget to commit and push!) with ./scripts/gcp-delete.sh

AWS

Expect that aws is installed locally. A ssh-key named 'learner' is required to access the account.

Azure

Expect that az is installed and configured locally. It will utilize your ~/.ssh/id_rsa.pub key.

Jupyter Book Tags

You can control the rendering of the book by adding "Tags" to the cells. To access tags select a cell then click the gears box on the top right of the browser tab to open up the properties.

Tags

  • To hide a cell add the tag remove-cell.

Bugs and Fixes

The bash kernel and Python do not like the new "bracketed paste" mode of the new bash/readline. To fix you can disable "bracketed paste" mode by doing

echo "set enable-bracketed-paste off" > ~/.inputrc

Note, this removes some copy/paste protection and recommended only for disposable VM's.