diff --git a/src/instructors/PreperationNewCourses.md b/src/instructors/PreperationNewCourses.md index 0936a8f42095e62721a7613e3fc8cdbe9af33dfb..a274eee36c7ee3c4ebd4602f962def7ec526a81b 100644 --- a/src/instructors/PreperationNewCourses.md +++ b/src/instructors/PreperationNewCourses.md @@ -37,33 +37,70 @@ This means: Only share read-only tokens to repositories which dont contain sensi In general, the following steps are required for adding a new profile to the cluster: -1. Choose a Jupyter Kernel -2. Prepare Jupyter Notebooks -3. Collect Python/Third-Party requirements -4. Prepare Dockerfile -5. Submit request for inclusion in profile list -6. Wait until request is reviewed and the new profile is included in the list +1. Setup a local test environemnt for preparing your Jupyter Environment +2. Choose a Jupyter Kernel +3. Create a new Git repository for Jupyter Notebooks and runtime environemnt +4. Prepare Jupyter Notebooks +5. Collect Python/Third-Party requirements +6. Adapt Dockerfile +7. Submit request for inclusion in profile list +8. Wait until request is reviewed and the new profile is included in the list -Hereby, steps 3 to 4 are optional and only required if the course requires a non-standard Jupyter kernel or special Python dependencies. +Hereby, steps 4.-6. are optional and only required if the course requires a non-standard Jupyter kernel or special Python dependencies. -### 1. Choose a Jupyter Kernel +### 1. Setup a local test environemnt for preparing your Jupyter Environment + +Please follow the instructions from the official Jupyter website: https://jupyter.org/install + +For Windows users, we recommend to use the Anaconda Python distribution. +Linux and macOS users can use Anaconda as well or simply rely on `pip` installed via the systems package manager. + +### 2. Choose a Jupyter Kernel Jupyter supports a variety of different programming languages via different _kernels_. -The original and most commonly used kernel using the iPython interpreter. +The original and most commonly used kernel using the [IPython](https://ipython.org/) interpreter. However also others exist. An updated lists of kernels can be found at the [Jupyter wiki](https://github.com/jupyter/jupyter/wiki/Jupyter-kernels). In principle, almost all of the existing kernels can be used on jupyter.rwth-aachen.de by creating custom runtime environments. -However, this step is not required in all cases. Some courses might just use a standard iPython environment. +Please consult the documentation for the installation of other kernels and add these instructions to the Dockerfile (step 6). -### 2. Prepare Jupyter Notebooks +However, in most cases the standard IPython kernel is used and no further steps are necessary. -We recommend to use the [RTWH Software Engineering Services](https://doc.itc.rwth-aachen.de/display/SES/Home) / [GitLab](https://git.rwth-aachen.de) to manage, track, distribute Jupyter Notebooks. +### 3. Create a new Git repository for Jupyter Notebooks and runtime environemnt + +We recommend to use the [RTWH Software Engineering Services](https://doc.itc.rwth-aachen.de/display/SES/Home) / [GitLab](https://git.rwth-aachen.de) to manage, track, distribute Jupyter Notebooks and the definition of the required runtime environment. This allows for a continous delivery of updates to Jupyter as well as welcomes contributions by Students to the Jupyter notebooks. -**Example Profile:** [https://git.rwth-aachen.de/jupyter/example-profile](https://git.rwth-aachen.de/jupyter/example-profile) +You can either use an existing Git repository, which might be already existing for a lecture or create a new one by forking our +[example profile](https://git.rwth-aachen.de/jupyter/example-profile). + +Please using the following link to create a new _fork_ of the example profile: [**create fork of example profile**](https://git.rwth-aachen.de/jupyter/example-profile/-/forks/new). + +After the fork has been completed, you can clone the fresh repo to your local machine: + +```bash +git clone git@git.rwth-aachen.de:/stvogel/my-new-course.git +cd my-new-course +``` + +### 4. Prepare Jupyter Notebooks + +A new profile can include a set of Jupyter notebooks which come along with it. +These Notebooks are will be synchronized from a Git repository every time a user enters the Jupyter environment. -### 3. Collect Python requirements +As such, the collection of Notebooks for a course can be expandend during the course of the semester. + +To start, please launch Jupyter on your local machine: + +```bash +jupyter lab +``` + +A new browser window will open and present you the Jupyter web interface and you should already see the list of existing files in the current Git repository. +Add new Notebooks and fill them with content to your wishes. + +### 5. Collect Python requirements Depending on the contents of the Jupyter Notebook, additional third-party Python packages might be required. Usually these external dependencies are collected in a `requirements.txt` or `environement.yml` file: @@ -73,11 +110,24 @@ Please have a look at the following links for further information: - [Creating Conda environments](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#create-env-file-manually) - [PIP Requirements Files](https://pip.pypa.io/en/stable/user_guide/#requirements-files) -### 4. Prepare Dockerfile +### 6. Adapt Dockerfile -We perpared an example Profile: https://git.rwth-aachen.de/jupyter/example-profile +Some profiles (e.g. when using special Jupyter Kernels) may require additional modifications to the runtime environemnt beyond the installation of new Python requirements. + +To accomodate these the user can modify the included Dockerfile to run arbitrary commands during the preperation of the environemnt. +Note that these commands are only executed during the Docker build phase. + +### 7. Publish Jupyter Notebooks and Dockerfile in Git repository + +After completing steps 2.-4., the resulting changes need to be commited to the Git repo and published on a Git hoster (e.g. RWTH GitLab or GitHub): + +```bash +git add . +git commit -m "first version of new profile" +git push +``` -### 5. Submit Questionaire for inclusion in profile list +### 8. Submit questionaire for inclusion in profile list Please fill out the following template and mail it to [jupyter-admin@lists.rwth-aachen.de](mailto:jupyter-admin@lists.rwth-aachen.de) in order to request the inclusing of your materials as a new profile.