Guide for teachers and collaborators
Instructions on using the CSC Notebooks environment as a teacher or for collaboration.
How to host a course or use CSC Notebooks for collaboration?
CSC Notebooks is built for hosting online courses. We support currently Jupyter and RStudio based content, with more options to come in the future. The intended workflow is that you create one workspace per course, and arrange your exercises in one or more applications in that workspace. Instead of a course you can also use CSC Notebooks for collaboration. The workflow is similar to creating a course environment and is described below.
1. Become a workspace owner and create a workspace
- Login to CSC Notebooks using your CSC account by choosing 'CSC Login' option after clicking 'Login'. If you don't have a CSC account yet, see the instructions on how to create new user account.
Manage workspacesfrom the left panel and create a new workspace.
- If you don't see
Manage workspacesoption, please
- Check that you logged in using your CSC account. Your user account on the bottom of the left navigation should look like 'csc/youraccountname'
- Reload your browser
- If the issue persists, contact CSC Notebooks support at email@example.com
2. Find or create custom images
- The easiest is to use an existing Docker image, look these repositories for suitable images:
- Docker image sources in notebooks-public-images repository.
- Rocker images for different RStudio set-ups.
- If you would need a few R/Python packages extra compared to existing images, it likely is easiest to add them run-time by the user.
- To create your own custom image, see Creating custom Docker images below.
3. Create an application in the workspace
Manage workspaces in the left navigation and select the workspace you want to work on. Create a new application
Application wizard or
Application template Template provides the base features for your application. Most of the templates are based on container images maintained by Notebooks team. Take a look at the image sources in notebooks-public-images repository. If you intend to use your own custom image, you can choose any template that matches your application type (Jupyter/RStudio).
Application name Give a valid meaningful name. This is the name under which participants will see the application.
Application description Fill a detailed description to helps users to understand more about the application.
* If using existing image, then pre-filled based on chosen Application template.
* If using own custom image, then URL of the Docker image. In case of Rahti, this would be something like
Session lifetime The maximum lifetime for a single session. Sessions are deleted when they expire, thus making room for other users.
Session memory RAM memory reserved for each session. Workspaces have a limit for total memory for concurrent sessions. Choosing a higher value here will affect the maximum number of concurrent sessions.
Labels Select the default labels or create custom labels. Labels are useful in searching applications. The icon for the application is also selected based on assigned labels.
Interface JupyterLab or old Jupyter Notebook. Applicable only for Jupyter based applications.
Download Method The location to download the course contents from. Choose
git clone if you wish to clone a git
Download from url if you have contents hosted in Allas or other HTTP accessible location and provide the url. Content is downloaded to $HOME folder of any instance by default.
The external location needs to be publicly accessible. For example git repositories should be public.
As an alternative, the course material can be provided through
shared folder. The workspace owner can prepare the
shared folder in advance. The folder is visible for everyone, but is read-only for course participants.
See data persistence document for more information.
Work folder per user Whether persistent user-based
my-work folder is available for users in this application.
This is enabled by default.
save as draft if you still need to test/change things in your application. Only after publication, which can be done here by choosing
publish immediately or from the application menu (Manage workspaces > your workspace > your Application > 3 bars on right end of application >
publish) later. Publication means that people with the join code can find the application. Your application will never appear for everyone. Only CSC Notebooks team can add self-learning and public-for-all notebooks.
4. Invite users
Once the content is ready, you can invite course participants / collaborators by sharing a workspace specific join code. The code can be found in
Manage workspaces view, in workspace list or on the Info tab of each workspace.
5. Promote users
Once the co-instructors/co-organizers/collaborators have signed in, you can find their name in the
members tab (under
manage workspaces), to give them rights to change things and see other participants sessions,
promote to co-owner from the Menu column next to the members name.
Co-owners can do everything the owner can, except demoting the owner or deleting the workspace. For collaboration purposes, all collaborators should have co-owner rights, to be able to write to the shared folder in the workspace.
Creating custom Docker images
If you cannot find a suitable image for your intended application, you will need to create and publish your own custom image for Notebooks. Image can be created on your own computer or for example cPouta instance.
- A computer to create the Docker image, it should have Docker installed. In general Linux/Mac computer is recommended. In Windows likely admin rights are needed and using Docker might be challenging.
- A place to upload the Docker image, for example CSC Rahti, DockerHub or Quay.io. In these instruction below CSC Rahti is used
Steps to create your own custom Docker image and host it on Rahti registry:
Create a Dockerfile
Jupyter notebook example
For JupyterLab with some conda packages use the following as minimal example:
# use jupyter minimal notebook as base for your image # it has eg conda already installed FROM jupyter/minimal-notebook #some first setup steps need to be run as root user USER root # set home environment variable to point to user directory ENV HOME /home/$NB_USER # install needed extra tools, eg ssh-client and less RUN apt-get update \ && apt-get install -y ssh-client less \ && apt-get clean # the user set here will be the user that students will use USER $NB_USER ### Installing the needed conda packages and jupyter lab extensions. # Run conda clean afterwards in same layer to keep image size lower RUN conda install --yes -c conda-forge <your-packages-here> \ && conda clean -afy
For other package management systems, adjust the last
RUN command accordingly. Make sure the package management system is available in
jupyter/minimal-notebook base image or install it yourself (same way as ssh-client and less are installed in above example).
To build custom R images, you do not need to start from scratch. Many pre-built R images are already available in docker registries. Especially, the rocker project contains a large set of images with various configurations provided in DockerHub. You can therefore start with one of these pre-existing images.
For adding packages or configurations you can use scripts provided by Rocker on their github page, edit them or write your own from scratch and copy them into the docker file system. These scripts usually contain system dependencies and required packages for your needs.
For RStudio with some packages, use the following Dockerfile as minimum example:
# Use Rocker RStudio as base for your image FROM rocker/rstudio # copy the desired installation script into docker file system, make sure that you have execute rights to the script COPY install_xx.sh /rocker_scripts/ # install the custom packages and system dependencies by running the script RUN /rocker_scripts/install_xx.sh
Below a few useful commands to install R packages from the command line or script, which can be used to write your own install script or edit the scripts provided by rocker:
# install a package with innstall2.r script install2.r --error --deps TRUE packagename # Install R packages from CRAN R -e "install.packages('packagename', repos='http://cran.rstudio.com/')" # Install R packages from Github using package managers like devtools and BiocManager. R --no-restore --no-save -e 'packagemanager::install_github("packagename",dependencies=TRUE)' # Install R packages while specifying a specific version R --no-restore --no-save -e 'packagemanager::install_version("packagename", version="version")' # Script execution R -e "source('/path/of/myscript.R')"
Build the image and test it
- Build the image from dockerfile to current directory
docker build -t "<yourimagename>" -f <yourimagename>.dockerfile .
Note that with Mac, or on any ARM host, you need to tell docker to build x64 images so that they are compatible with our cloud hosts. This can be done using "docker buildx".
docker buildx build --platform linux/amd64 ....
Another alternative is to build the image on an x64 VM, for example on pouta.csc.fi.
- Test your image.
-p 8888:8787means bind Docker port 8787 to host port 8888.
- If using cPouta, you need to open the host port also from Security groups.
- Open Jupyter/RStudio with web-browser:
docker run -p 8888:8787 <yourimagename>
Add the image to Rahti registry
Login to Rahti registry:
- In a web browser, open to Rahti registry and log in with your CSC username
- On the
Overviewpage, find the
login commandssection and the
Log into the registrycommand.
- In terminal, use the command to log in to Rahti registry
Tag your docker image, eg based on versions (here: v0.1):
docker tag <yourimagename> docker-registry.rahti.csc.fi/<yourrahtiproject>/<yourimagename>:v0.1
Push your docker image to Rahti registry:
sudo docker push docker-registry.rahti.csc.fi/<yourrahtiproject>/<yourimagename>:v0.1
The new image should become visible in Rahti registry, see the ´Images´ tab. Now everything should be ready continuing from step 3 above.
Security guidelines for Workspace owners
- CSC Notebooks is not intended for sensitive data. Do not store sensitive data or data sets.
- Share join code only with users you wish to join your workspace.
- If you are creating custom images for your course, do not store any keys or sensitive data in the image.
- Delete the workspace as soon as the course is over.