Add info how to persist user data (#1977)

* Add info how to persist user data

* Improve wording

* Add note

* Better wording

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.

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 <package>` 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.

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.

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: