Updated USer Guide for XAIL Docker Edition

doc/user_guide/docker/docker-usage.md

@@ -24,7 +24,15 @@ LISTEN_IP=0.0.0.0
 VOLUME=my-vol
 ```
 
-## Starting a Docker Container from the Docker Image
+## Creating a Docker Container from the Docker Image
+
+You can use an Exasol database with AI-Lab in two ways
+* [External Exasol database](#ai-lab-with-external-exasol-database)
+* Integrated [Exasol Docker-DB](#ai-lab-managing-exasol-docker-db-internally) managed by AI-Lab
+
+### AI-Lab with External Exasol Database
+
+In this scenario the AI-Lab Docker container does not need access to the Docker daemon.
 
 The following command will
 * Download the Docker image for the specified version `$VERSION` of the AI-Lab if the image of the specified version is not yet available in your Docker service
@@ -40,18 +48,17 @@ docker run \
   exasol/ai-lab:${VERSION}
 ```
 
-Please note
-* This is how you can start the AI-Lab if you are going to connect to an existing Exasol database.
-* The [following section](#enable-ai-lab-to-access-the-docker-daemon) shows how to enable the AI-Lab to start an instance of Exasol Docker-DB.
-* If you want to use a newer version of the AI-Lab then please delete Docker volumes created with older versions.
+If you want to use a newer version of the AI-Lab then please [delete Docker volumes](managing-user-data.md#replacing-the-docker-volume) created with older versions.
 
 Additional options
 * Add option `--detach` to run the container in the background but please note that the initial welcome message with instructions will be hidden then, see also command [`docker logs`](https://docs.docker.com/engine/reference/commandline/container_logs/).
 * If port `49494` is not available on your daemon machine you can forward port `49494` of the Jupyter server in the Docker container to another port, e.g. `55555`, on the daemon machine with `--publish ${LISTEN_IP}:55555:49494`
 
-### Enable AI-Lab to Access the Docker Daemon
+### AI-Lab Managing Exasol Docker-DB Internally
+
+In this scenario you must enable the AI-Lab Docker container to access the Docker daemon.
 
-The following command will enable AI-Lab to start an instance of Exasol Docker-DB, however
+**Please note**
 * Additional [Limitations and security risks](os-setup.md#enabling-exasol-ai-lab-to-use-docker-features) apply.
 * Only file system objects on the daemon machine can be mounted. This applies to ordinary directories as well as the `docker.sock`.
 * On Windows mounting `docker.sock` only works with Docker Desktop with WSL 2.
@@ -63,6 +70,24 @@ docker run \
   exasol/ai-lab:${VERSION}
 ```
 
+## Restarting a Stopped Container
+
+In general we recommend to restart a stopped container instead of creating a new one. This has the benefit of keeping [additional dependencies](#installing-additional-dependencies) that you did install:
+
+```shell
+docker start <CONTAINER>
+```
+
+**Please note**
+* If you accidently created a new AI-Lab Docker container and the stopped container still exists please remove the new container and restart the existing one.
+* If there is no stopped AI-Lab container and you are using Exasol Docker-DB you need to link the newly created container to the Exasol Docker-DB network `db_network_DemoDb`.
+
+```shell
+docker network connect db_network_DemoDb <CONTAINER>
+```
+
+See also https://docs.docker.com/engine/reference/commandline/network_connect/
+
 ## Connecting to Jupyter Service
 
 When starting AI-Lab as Docker container the command line will display a welcome message showing connection instructions and a reminder to change the default password:

doc/user_guide/docker/managing-user-data.md

@@ -88,4 +88,4 @@ The following commands will remove the container with ID `${CONTAINER}` and the
 ```shell
 docker rm -f ${CONTAINER}
 docker volume rm -f ${VOLUME}
-```
+```

doc/user_guide/docker/os-setup.md

@@ -25,4 +25,4 @@ In all scenarios the daemon machine must allow running the Exasol Docker-DB with
 
 Please note that enabling Exasol AI-Lab to use Docker features creates security risks. In particular, code running inside the AI-Lab could create privileged containers, mount the file system of the machine running the Docker daemon, and gain root access to it. For details see https://jpetazzo.github.io/2015/09/03/do-not-use-docker-in-docker-for-ci/, section "The socket solution".
 
-Section [Enable AI-Lab to Access the Docker Daemon](docker-usage.md#enable-ai-lab-to-access-the-docker-daemon) shows the corresponding command line options, for details see [Docker FAQ](https://docs.docker.com/desktop/faqs/general/#how-do-i-connect-to-the-remote-docker-engine-api).
+Section [AI-Lab Managing Exasol Docker-DB Internally](docker-usage.md#ai-lab-managing-exasol-docker-db-internally) shows the corresponding command line options, for details see [Docker FAQ](https://docs.docker.com/desktop/faqs/general/#how-do-i-connect-to-the-remote-docker-engine-api).