From 0ab34f7b1f3b2280b678a5ba21797f7d38067c33 Mon Sep 17 00:00:00 2001
From: Pantelis Sopasakis <p.sopasakis@gmail.com>
Date: Tue, 26 Mar 2024 14:50:29 +0000
Subject: [PATCH] [ci skip] dockers docs (readme)

---
 docker/README.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 46 insertions(+), 2 deletions(-)

diff --git a/docker/README.md b/docker/README.md
index eaf02611..6c1def73 100644
--- a/docker/README.md
+++ b/docker/README.md
@@ -13,13 +13,57 @@ docker pull alphaville/open
 and then run it with
 
 ```console
-docker run -p 8888:8888 -it alphaville/open
+docker run --name open-jupyter -p 8888:8888 -it alphaville/open
+```
+
+Note that this will create a docker container with name `open-jupyter`. If you stop it, you can restart it with (don't do `docker run` again)
+
+```console
+docker start -ai open-jupyter
 ```
 
 ## What it does
 
 It starts a Jupyter Notebook at [localhost:8888](http://localhost:8888) without a password.
 
+## What's in the docker image?
+
+This docker image is build from `debian:stable` and contains:
+
+- A virtual environment (with Python 3)
+- Opengen [v0.8.0](https://github.com/alphaville/optimization-engine/releases/tag/opengen-0.8.0)
+- The [latest version](https://crates.io/crates/optimization_engine) of the OpEn rust solver is installed automatically
+- Jupyter notebook (runs automatically when the image runs)
+
+
+## How to open a terminal into the docker image
+
+Just 
+
+```console
+docker exec -it open-jupyter bash
+```
+
+This will open a bash shell to the docker image with name `open-jupyter`; this is the name we specified above when we ran the image (using `--name open-jupyter`). In this bash shell, the virtual environment on which the Jupyter notebook is running is enabled by default. 
+
+
+### How to run with specified volume
+
+Firstly, you need to create a volume. You only need to do this once (unless you want to create different volumes). As an example, let us create a docker volume with name `OpEnVolume`:
+
+```console
+docker volume create OpEnVolume
+```
+
+Next, let us run the image `alphaville/open:0.5.0` with the above volume:
+
+```console
+docker run --name open-jupyter \
+           --mount source=OpEnVolume,destination=/open \
+           -p 8888:8888 \
+           -it alphaville/open:0.5.0
+```
+
 ## Set a password
 
 To set up a password for your Python Notebook:
@@ -33,7 +77,7 @@ docker run -e JUPYTER_NOTEBOOK_PASSWORD=... -p 8888:8888 -it alphaville/open
 
 For example, let's say you want to set the password **open**. Then do
 
-```
+```console
 docker run   \
   -e JUPYTER_NOTEBOOK_PASSWORD=sha1:898ca689bf37:2ee883bfd6ffe82a749a86e37964700bd06a2ff9  \
   -p 8888:8888 -it alphaville/open