This repository provides resources for creating custom images on Coursera Labs. It includes files to build and run images on Coursera Labs, including the source files to set up our (5) base images.
This resource may be particularly helpful for those looking to:
- add small modifications to the existing default images on Coursera Labs
- add a submit button or bypass the token authentication flow for your own Jupyter Notebook images
-
Install Docker if not installed already
-
Build run-lab image
docker build -t run-lab -f run-lab/Dockerfile .
The
run-lab
image is a Dockerized version ofrun-lab/coursera-lab.py
script.run-lab/coursera-lab.py
script simulates Coursera Labs Docker build and run procedures. -
Create a folder with your custom image files and
manifest.json
The folders
jupyter/datascience-notebook/v2
,jupyter/scipy-notebook/v2
andjupyter/tensorflow-notebook/v2
include the files that build our v2 base images. Please feel free to use these folders to test out this build flow.We also strongly recommend using the provided images as the basis for your custom images.
Additionally, Coursera Labs script uses
manifest.json
to read configurations specific to your image. Details aboutmanifest.json
can be found here. -
Build your image locally
Jupyter Notebook images: Build Jupyter Notebook image by running the following command. The
--add-submit-button
option also takes care of the token authentication flow, so you should use this option for all Jupyter Notebook images you plan on using on Coursera Labs../run-lab/run.sh build <path to image folder> --add-submit-button
This will create a new folder called
/generated
under your<path to image folder>
.Other web app images: Build image of an application other than Jupyter Notebook by running the following command:
./run-lab/run.sh build <path to image folder>
-
Test your image locally Run an instance of the built custom image by running the following command:
./run-lab/run.sh run <path to image folder>
For example, if you built the tensorflow-notebook image that we provided,
./run-lab/run.sh run jupyter/tensorflow-notebook/v2
If you see a message that asks:
Tell me which volumes to mount for the following container volumes
, enter the local machine path from which files are to be mounted at that specific mount path.You'll see a message that says
Starting instance of <image-name> listening on localhost:<port>
. Then go tolocalhost:<port>
in your browser to play with the custom image. -
Upload your image to the platform
The build step should have created a folder called
/generated
under your<path to image folder>
. In this folder, there will be aDockerfile
with all the relevant commands to build the image on the platform.If you do not need any folders or files outside of the
Dockerfile
, you can create a .zip of theDockerfile
and then upload it as a Custom Image to the Lab Manager using the "Upload Build Files" button.If you do need any folders or files to successfully build the image (e.g.
requirements.txt
), make sure to include these files in the.zip
file such that theDockerfile
can reference it successfully during the build process. Make sure theDockerfile
is located in the root directory.You do not need to add
manifest.json
to the.zip
file to upload successfully to the platform, unless yourDockerfile
explicitly uses this.
Coursera Labs script uses manifest.json
to read configurations specific to your image. Below is an example of manifest.json
file.
{
"name": "coursera/tensorflow-notebook",
"version": "1.0",
"httpPort": 8888,
"mounts": [
{
"path": "/home/jovyan/work"
}
],
"environmentVars": [
{
"name": "NAME",
"value": "VALUE"
}
]
}
- name: the image name
- version: optional, the image tag
- httpPort: the exposed port of the container
- mounts: mount list of volumes to the container. Files mounted at these mount paths persist across lab sessions in Coursera Labs. In other words, you need at least one mount path to persist files across lab sessions.
- environmentVars: optional, list of environment variables of the container
We're adding in unit testing frameworks to give us more confidence that our images do what we want them to do. For now, we only have unit tests in place for our nbgrader images, to verify that traceback redaction is working as expected. You can take advantage of these unit-tests with the command
./run-lab/run.sh test jupyter/nbgrader
You will be prompted to enter a filepath to which the rich feedback file will generated.
Example #1: Build tensorflow-notebook v2 image under build directory jupyter/tensorflow-notebook/v2
. Dockerfile
and manifest.json
are required to start the build.
./run-lab/run.sh build jupyter/tensorflow-notebook/v2
Example #2: Build tensorflow-notebook image with Coursera submit button. This only works with Jupyter Notebook images.
./run-lab/run.sh build jupyter/tensorflow-notebook/v2 --add-submit-button
Example #3: Run an instance of the built tensorflow-notebook image.
./run-lab/run.sh run jupyter/tensorflow-notebook/v2