diff --git a/README.md b/README.md index ad9429d82b..b9eb609737 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 1d41719056..a072d58f4c 100644 --- a/docs/using/faq.md +++ b/docs/using/faq.md @@ -1,5 +1,27 @@ # 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 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). + + ```{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` command. + ``` + +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 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 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 8b95806739..cfeb4cedf5 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 822a2efcc5..d8761fbfe9 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: