diff --git a/docs/using/recipes.md b/docs/using/recipes.md index 2084a839..4e17fc24 100644 --- a/docs/using/recipes.md +++ b/docs/using/recipes.md @@ -1,14 +1,13 @@ # Contributed Recipes Users sometimes share interesting ways of using the Jupyter Docker Stacks. -We encourage users to [contribute these recipes](../contributing/recipes.md) to the documentation in case they prove -useful to other members of the community by submitting a pull request to `docs/using/recipes.md`. +We encourage users to [contribute these recipes](../contributing/recipes.md) to the documentation in case they prove helpful to other community members by submitting a pull request to `docs/using/recipes.md`. The sections below capture this knowledge. ## Using `sudo` within a container Password authentication is disabled for the `NB_USER` (e.g., `jovyan`). -This choice was made to avoid distributing images with a weak default password that users ~might~ will forget to change before running a container on a publicly accessible host. +We made this choice to avoid distributing images with a weak default password that users ~might~ will forget to change before running a container on a publicly accessible host. You can grant the within-container `NB_USER` passwordless `sudo` access by adding `-e GRANT_SUDO=yes` and `--user root` to your Docker command line or appropriate container orchestrator config. @@ -41,7 +40,7 @@ Then build a new image. docker build --rm -t jupyter/my-datascience-notebook . ``` -To use a requirements.txt file, first create your `requirements.txt` file with the listing of +To use a requirements.txt file, first, create your `requirements.txt` file with the listing of packages desired. Next, create a new Dockerfile like the one shown below. @@ -73,13 +72,13 @@ Ref: [docker-stacks/commit/79169618d571506304934a7b29039085e77db78c](https://git ## Add a Python 2.x environment Python 2.x was removed from all images on August 10th, 2017, starting in tag `cc9feab481f7`. -You can add a Python 2.x environment by defining your own Dockerfile inheriting from one of the images like so: +You can add a Python 2.x environment by defining your Dockerfile inheriting from one of the images like so: ```dockerfile # Choose your desired base image FROM jupyter/scipy-notebook:latest -# Create a Python 2.x environment using conda including at least the ipython kernel +# Create a Python 2.x environment using conda, including the ipython kernel # and the kernda utility. Add any additional packages you want available for use # in a Python 2 notebook to the first line here (e.g., pandas, matplotlib, etc.) RUN mamba create --quiet --yes -p "${CONDA_DIR}/envs/python2" python=2.7 ipython ipykernel kernda && \ @@ -100,7 +99,7 @@ Ref: ## Add a Python 3.x environment The default version of Python that ships with conda/ubuntu may not be the version you want. -To add a conda environment with a different version and make it accessible to Jupyter, the instructions are very similar to Python 2.x but are slightly simpler (no need to switch to `root`): +The instructions o add a conda environment with a different version and make it accessible to Jupyter are very similar to Python 2.x. Still, they are slightly simpler (no need to switch to `root`): ```dockerfile # Choose your desired base image @@ -169,7 +168,7 @@ Once built, run using the command: ```bash docker run -it --rm -p 8888:8888 \ - -p 8787:8787 jupyter/scipy-dasklabextension:latest + -p 8787:8787 jupyter/scipy-dasklabextension:latest ``` Ref: @@ -184,7 +183,7 @@ Ref: ## Slideshows with Jupyter and RISE -[RISE](https://github.com/damianavila/RISE) allows via extension to create live slideshows of your +[RISE](https://github.com/damianavila/RISE) allows via an extension to create live slideshows of your notebooks, with no conversion, adding javascript Reveal.js: ```bash @@ -200,7 +199,7 @@ Credit: [Paolo D.](https://github.com/pdonorio) based on ## xgboost -You need to install conda-forge's gcc for Python xgboost to work properly. +You need to install conda-forge's gcc for Python xgboost to work correctly. Otherwise, you'll get an exception about libgomp.so.1 missing GOMP_4.0. ```bash @@ -218,12 +217,12 @@ pip install --quiet --no-cache-dir xgboost && \ ## Running behind a nginx proxy -Sometimes it is useful to run the Jupyter instance behind a nginx proxy, for instance: +Sometimes it is helpful to run the Jupyter instance behind a nginx proxy, for example: - you would prefer to access the notebook at a server URL with a path (`https://example.com/jupyter`) rather than a port (`https://example.com:8888`) - you may have many different services in addition to Jupyter running on the same server, and want - to nginx to help improve server performance in manage the connections + to nginx to help improve server performance in managing the connections Here is a [quick example NGINX configuration](https://gist.github.com/cboettig/8643341bd3c93b62b5c2) to get started. You'll need a server, a `.crt` and `.key` file for your server, and `docker` & `docker-compose` installed. @@ -243,7 +242,7 @@ Ref: ## Manpage installation Most containers, including our Ubuntu base image, ship without manpages installed to save space. -You can use the following dockerfile to inherit from one of our images to enable manpages: +You can use the following Dockerfile to inherit from one of our images to enable manpages: ```dockerfile # Choose your desired base image @@ -262,9 +261,9 @@ RUN rm /etc/dpkg/dpkg.cfg.d/excludes && \ USER ${NB_UID} ``` -Adding the documentation on top of an existing singleuser image wastes a lot of space and requires -reinstalling every system package, which can take additional time and bandwidth; the -`datascience-notebook` image has been shown to grow by almost 3GB when adding manapages in this way. +Adding the documentation on top of the existing single-user image wastes a lot of space and requires +reinstalling every system package. Which can take additional time and bandwidth; the +`datascience-notebook` image has been shown to grow by almost 3GB when adding manpages in this way. Enabling manpages in the base Ubuntu layer prevents this container bloat. To achieve this, use the previous `Dockerfile` with the original ubuntu image (`ubuntu:focal`) as your base container: @@ -274,7 +273,7 @@ To achieve this, use the previous `Dockerfile` with the original ubuntu image (` ARG BASE_CONTAINER=ubuntu:focal-20200423@sha256:238e696992ba9913d24cfc3727034985abd136e08ee3067982401acdc30cbf3f ``` -For Ubuntu 18.04 (bionic) and earlier, you may also require to workaround for a mandb bug, which was fixed in mandb >= 2.8.6.1: +For Ubuntu 18.04 (bionic) and earlier, you may also require to a workaround for a mandb bug, which was fixed in mandb >= 2.8.6.1: ```dockerfile # https://git.savannah.gnu.org/cgit/man-db.git/commit/?id=8197d7824f814c5d4b992b4c8730b5b0f7ec589a @@ -293,10 +292,10 @@ We also have contributed recipes for using JupyterHub. ### Use JupyterHub's dockerspawner -In most cases for use with DockerSpawner, given any image that already has a notebook stack set up, +In most cases for use with DockerSpawner, given an image that already has a notebook stack set up, you would only need to add: -1. install the jupyterhub-singleuser script (for the right Python) +1. install the jupyterhub-singleuser script (for the correct Python version) 2. change the command to launch the single-user server Swapping out the `FROM` line in the `jupyterhub/singleuser` Dockerfile should be enough for most @@ -480,22 +479,22 @@ Credit: [britishbadger](https://github.com/britishbadger) from [docker-stacks/is (Adapted from [issue 728](https://github.com/jupyter/docker-stacks/issues/728)) The default security is very good. -There are use cases, encouraged by containers, where the jupyter container and the system it runs within, lie inside the security boundary. -In these use cases it is convenient to launch the server without a password or token. +There are use cases, encouraged by containers, where the jupyter container and the system it runs within lie inside the security boundary. +It is convenient to launch the server without a password or token in these use cases. In this case, you should use the `start.sh` script to launch the server with no token: -For jupyterlab: +For JupyterLab: ```bash docker run jupyter/base-notebook:b418b67c225b \ - start.sh jupyter lab --LabApp.token='' + start.sh jupyter lab --LabApp.token='' ``` For jupyter classic: ```bash docker run jupyter/base-notebook:b418b67c225b \ - start.sh jupyter notebook --NotebookApp.token='' + start.sh jupyter notebook --NotebookApp.token='' ``` ## Enable nbextension spellchecker for markdown (or any other nbextension) @@ -546,9 +545,9 @@ RUN echo "from pyspark.sql import SparkSession" > /tmp/init-delta.py && \ rm /tmp/init-delta.py ``` -## Add Custom Font in Scipy notebook +## Add Custom Fonts in Scipy notebook -The example below is a Dockerfile to load Source Han Sans with normal weight which is usually used for web. +The example below is a Dockerfile to load Source Han Sans with normal weight, usually used for the web. ```dockerfile FROM jupyter/scipy-notebook:latest