From d97a2722a0fe7dea8ae11df43e20ea1f306ec6c9 Mon Sep 17 00:00:00 2001 From: Ayaz Salikhov Date: Sun, 20 Aug 2023 17:19:08 +0200 Subject: [PATCH 1/4] Add info how to persist user data --- README.md | 4 ++-- docs/using/faq.md | 13 +++++++++++++ docs/using/recipes.md | 8 ++++++++ docs/using/running.md | 8 ++++---- 4 files changed, 27 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index ad9429d82..b9eb60973 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ and want to launch a single Jupyter Application in a container. The [User Guide on ReadTheDocs](https://jupyter-docker-stacks.readthedocs.io/en/latest/) describes additional uses and features in detail. -**Example 1:** +### Example 1 This command pulls the `jupyter/scipy-notebook` image tagged `2023-08-19` from Docker Hub if it is not already present on the local host. It then starts a container running a Jupyter Server with the JupyterLab frontend and exposes the container's internal port `8888` to port `10000` of the host machine: @@ -43,7 +43,7 @@ where: The container remains intact for restart after the Server exits. -**Example 2:** +### Example 2 This command pulls the `jupyter/datascience-notebook` image tagged `2023-08-19` from Docker Hub if it is not already present on the local host. It then starts an _ephemeral_ container running a Jupyter Server with the JupyterLab frontend and exposes the server on host port 10000. diff --git a/docs/using/faq.md b/docs/using/faq.md index 1d4171905..b61a5e8c4 100644 --- a/docs/using/faq.md +++ b/docs/using/faq.md @@ -1,5 +1,18 @@ # Frequently Asked Questions (FAQ) +## How to persist user data + +There are 2 types of data, which you might want to persist. + +1. If you want to persist packages (mamba/conda/pip/apt), then you should create an inherited image and install them only once while building your Dockerfile. + An example for using `mamba` and `pip` in a child image is available + [here](./recipes.md#using-mamba-install-recommended-or-pip-install-in-a-child-docker-image) +2. If you want to persist user files like `python` scripts, notebooks, text files and so on (created by you), then you should use a + [Docker bind mount](https://docs.docker.com/storage/bind-mounts/) or + [Docker Volume](https://docs.docker.com/storage/volumes/). + You can find an [example of using bind mount here](./running.md#example-2). + There is a [mount troubleshooting section](./troubleshooting.md#permission-denied-when-mounting-volumes) if you experience any issues. + ## Why we do not add your favorite package We have lots of users with different packages they want to use. diff --git a/docs/using/recipes.md b/docs/using/recipes.md index 8b9580673..cfeb4cedf 100644 --- a/docs/using/recipes.md +++ b/docs/using/recipes.md @@ -44,6 +44,14 @@ Then build a new image. docker build --rm --tag my-custom-image . ``` +You can then run the image as follows: + +```bash +docker run -it --rm \ + -p 8888:8888 \ + my-custom-image +``` + ## Add a custom conda environment and Jupyter kernel The default version of `Python` that ships with the image may not be the version you want. diff --git a/docs/using/running.md b/docs/using/running.md index 822a2efcc..d8761fbfe 100644 --- a/docs/using/running.md +++ b/docs/using/running.md @@ -13,7 +13,7 @@ You can launch a local Docker container from the Jupyter Docker Stacks using the There are numerous ways to configure containers using the CLI. The following are some common patterns. -**Example 1:** +### Example 1 This command pulls the `jupyter/scipy-notebook` image tagged `2023-08-19` from Docker Hub if it is not already present on the local host. It then starts a container running Jupyter Server with the JupyterLab frontend and exposes the server on host port 8888. @@ -51,7 +51,7 @@ docker rm 221331c047c4 # 221331c047c4 ``` -**Example 2:** +### Example 2 This command pulls the `jupyter/r-notebook` image tagged `2023-08-19` from Docker Hub if it is not already present on the local host. It then starts a container running Server and exposes the server on host port 10000. @@ -72,7 +72,7 @@ So, new notebooks will be saved there, unless you change the directory in the fi To change the default directory, you will need to specify `ServerApp.root_dir` by adding this line to previous command: `start-notebook.sh --ServerApp.root_dir=/home/jovyan/work`. ``` -**Example 3:** +### Example 3 This command pulls the `jupyter/all-spark-notebook` image currently tagged `latest` from Docker Hub if an image tagged `latest` is not already present on the local host. It then starts a container named `notebook` running a JupyterLab server and exposes the server on a randomly selected port. @@ -118,7 +118,7 @@ docker rm notebook An alternative to using the Docker CLI is to use the Podman CLI. Podman is mostly compatible with Docker. -**Example 4:** +### Podman example If we use Podman instead of Docker in the situation given in _Example 2_, it will look like this: From 41b72d2cc967d016ccb1142d0a0f09ff146444d3 Mon Sep 17 00:00:00 2001 From: Ayaz Salikhov Date: Sun, 20 Aug 2023 17:30:08 +0200 Subject: [PATCH 2/4] Improve wording --- docs/using/faq.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/using/faq.md b/docs/using/faq.md index b61a5e8c4..e6efbf1ac 100644 --- a/docs/using/faq.md +++ b/docs/using/faq.md @@ -4,14 +4,16 @@ There are 2 types of data, which you might want to persist. -1. If you want to persist packages (mamba/conda/pip/apt), then you should create an inherited image and install them only once while building your Dockerfile. +1. If you want to persist your environment (i.e. packages installed by `mamba`, `conda`, `pip`, `apt-get` and so on), + then you should create an inherited image and install them only once while building your Dockerfile. An example for using `mamba` and `pip` in a child image is available [here](./recipes.md#using-mamba-install-recommended-or-pip-install-in-a-child-docker-image) -2. If you want to persist user files like `python` scripts, notebooks, text files and so on (created by you), then you should use a +2. If you want to persist user-data (files created by you, like `python` scripts, notebooks, text files and so on), + then you should use a [Docker bind mount](https://docs.docker.com/storage/bind-mounts/) or [Docker Volume](https://docs.docker.com/storage/volumes/). - You can find an [example of using bind mount here](./running.md#example-2). - There is a [mount troubleshooting section](./troubleshooting.md#permission-denied-when-mounting-volumes) if you experience any issues. + You can find [an example of using bind mount here](./running.md#example-2). + There is also [a mount troubleshooting section](./troubleshooting.md#permission-denied-when-mounting-volumes) if you experience any issues. ## Why we do not add your favorite package From fcdbb5dd97993de6bfe7ab5f074f481c917b887d Mon Sep 17 00:00:00 2001 From: Ayaz Salikhov Date: Sun, 20 Aug 2023 17:38:27 +0200 Subject: [PATCH 3/4] Add note --- docs/using/faq.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/using/faq.md b/docs/using/faq.md index e6efbf1ac..08da1ac32 100644 --- a/docs/using/faq.md +++ b/docs/using/faq.md @@ -7,7 +7,14 @@ There are 2 types of data, which you might want to persist. 1. If you want to persist your environment (i.e. packages installed by `mamba`, `conda`, `pip`, `apt-get` and so on), then you should create an inherited image and install them only once while building your Dockerfile. An example for using `mamba` and `pip` in a child image is available - [here](./recipes.md#using-mamba-install-recommended-or-pip-install-in-a-child-docker-image) + [here](./recipes.md#using-mamba-install-recommended-or-pip-install-in-a-child-docker-image). + + ```{note} + If you install a package inside a running container (for example you run `pip install ` in a terminal), + it won't be preserved when you next run your image. + To make it work, install this package in your inherited image and rerun `docker build`. + ``` + 2. If you want to persist user-data (files created by you, like `python` scripts, notebooks, text files and so on), then you should use a [Docker bind mount](https://docs.docker.com/storage/bind-mounts/) or From 83b7fe6de60660de011a1a17a4ade70b11997282 Mon Sep 17 00:00:00 2001 From: Ayaz Salikhov Date: Sun, 20 Aug 2023 17:43:24 +0200 Subject: [PATCH 4/4] Better wording --- docs/using/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/using/faq.md b/docs/using/faq.md index 08da1ac32..a072d58f4 100644 --- a/docs/using/faq.md +++ b/docs/using/faq.md @@ -12,7 +12,7 @@ There are 2 types of data, which you might want to persist. ```{note} If you install a package inside a running container (for example you run `pip install ` in a terminal), it won't be preserved when you next run your image. - To make it work, install this package in your inherited image and rerun `docker build`. + To make it work, install this package in your inherited image and rerun `docker build` command. ``` 2. If you want to persist user-data (files created by you, like `python` scripts, notebooks, text files and so on),