From 71f72ce758d748681a2a6b525628513ff03202b9 Mon Sep 17 00:00:00 2001 From: ckunki Date: Tue, 20 Feb 2024 11:20:28 +0100 Subject: [PATCH] Fixed review findings. --- doc/user_guide/ami-usage.md | 2 -- doc/user_guide/docker/docker-usage.md | 12 ++++++------ doc/user_guide/docker/intro.md | 2 +- doc/user_guide/docker/managing-user-data.md | 4 ++-- doc/user_guide/docker/os-setup.md | 8 ++++---- doc/user_guide/docker/prerequisites.md | 2 +- doc/user_guide/editions.md | 9 +++++---- 7 files changed, 19 insertions(+), 20 deletions(-) diff --git a/doc/user_guide/ami-usage.md b/doc/user_guide/ami-usage.md index 6b38052f..1b38a0b0 100644 --- a/doc/user_guide/ami-usage.md +++ b/doc/user_guide/ami-usage.md @@ -6,8 +6,6 @@ The naming scheme is: "_Exasol-AI-Lab-${VERSION}_", e.g. "_Exasol-AI-Lab-5.0.0_" The AMI is currently only available in the AWS region `eu-central-1`. -If you want to use the image in another region, you need to copy it before. - Check the [AWS documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/CopyingAMIs.html) for details about how to copy the image. ## Overview diff --git a/doc/user_guide/docker/docker-usage.md b/doc/user_guide/docker/docker-usage.md index dc28bc63..32f41662 100644 --- a/doc/user_guide/docker/docker-usage.md +++ b/doc/user_guide/docker/docker-usage.md @@ -2,13 +2,13 @@ Using Exasol AI-Lab Docker Edition requires some specific [prerequisites](prerequisites.md) but also offers additional benefits. -The [Operating System and Setup Guide](os-setup.md) helps you first the initial system setup as using Docker can be simple on Linux systems but more complex on other platforms and in distributed scenarios. +The [Operating System and Setup Guide](os-setup.md) helps you with the initial system setup. AI-Lab also offers a [short introduction](intro.md) to Docker Images and Containers if you are new to this technology. ## Defining Environment Variables -The Unix shell commands in the following sections will use some environment variables to make the commands portable and enable to adapt to your specific preferences while at the same time maintaining the ability to execute the commands verbatim without any change: +The Unix shell commands in the following sections will use some environment variables. By this you can adapt the commands to your specific preferences while still being able to to execute them literally: * Variable `VERSION` refers to the version of Exasol AI-Lab Docker Edition you want to use, alternativly you can use `latest`. * Variable `VOLUME` is expected to contain the name of your Docker volume, see [Managing User Data](managing-user-data.md). * Variable `LISTEN_IP` defines the range of IP-addresses allowed to connect to the forwarded Jupyter port. @@ -16,7 +16,7 @@ The Unix shell commands in the following sections will use some environment vari * For local setups, we recommend `127.0.0.1`. * Please contact your IT department if there are security restrictions. -Here are some sample values — please change to your needs: +Here is an example: ```shell VERSION=0.2.0 @@ -27,11 +27,11 @@ VOLUME=my-vol ## Starting a Docker Container from the Docker Image The following command will -* Download the Docker image for the specified version `$VERSION` of the AI-Lab if not yet available in your Docker service +* 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 * Run a Docker container using this image * Mount the volume `$VOLUME` to the directory `/root/notebooks` inside the container * If the volume does not exist yet, then it will be created automatically. -* Forward port `49494` on the [daemon machine](prerequisites.md) allowing connections from all IP addresses matched by `$LISTEN_IP` +* Forward port `49494` on the [daemon machine](prerequisites.md) to allow connections from all IP addresses matched by `$LISTEN_IP` ```shell docker run \ @@ -41,7 +41,7 @@ docker run \ ``` Please note -* In this scenario you need to connect the AI-Lab to an Exasol database that is already up and running. +* 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. diff --git a/doc/user_guide/docker/intro.md b/doc/user_guide/docker/intro.md index e8168aca..fd29c138 100644 --- a/doc/user_guide/docker/intro.md +++ b/doc/user_guide/docker/intro.md @@ -17,7 +17,7 @@ While a container is running you can * Connect to IP ports exposed by the container * Open a shell inside the container to interact with the container's file system or processes running inside the container, see command [`docker exec`](https://docs.docker.com/engine/reference/commandline/container_exec/) -When removing the container, all its processes are stopped and all changes to its file system are discarded. When you start a new container using the same image then all changes will be lost and the contents of its file system will be identical as defined by the image. +When removing the container, all its processes are stopped and all changes to its file system are discarded. When you start a new container using the same image then all changes will be lost and the file system contents will reset to default. Please see [Managing User Data](managing-user-data.md) for preserving changes in the Jupyter notebook files and the [Secure Configuration Storage](secure-configuration-storage.md), though. diff --git a/doc/user_guide/docker/managing-user-data.md b/doc/user_guide/docker/managing-user-data.md index 9132157d..9a883bef 100644 --- a/doc/user_guide/docker/managing-user-data.md +++ b/doc/user_guide/docker/managing-user-data.md @@ -78,13 +78,13 @@ You can also delete the old volume: * Docker volumes can only be deleted if there aren't any Docker containers using them. * Also stopped containers still prevent Docker volumes from being deleted. -Use the following command to find out the ID of existing Docker containers, including also stopped containers, see also [User Guide for AI-Lab Docker edition](docker-usage.md#logging-in-to-the-docker-container): +Use the following command to find out the ID of existing Docker containers, including the stopped ones, see also [User Guide for AI-Lab Docker edition](docker-usage.md#logging-in-to-the-docker-container): ```shell docker ps --all ``` -The following commands will remove the container with ID `${CONTAINER}` and the volume: +The following commands will remove the container with ID `${CONTAINER}` and the volume with the name `${VOLUME}`: ```shell docker rm -f ${CONTAINER} diff --git a/doc/user_guide/docker/os-setup.md b/doc/user_guide/docker/os-setup.md index 8893ec0a..c3c7bfea 100644 --- a/doc/user_guide/docker/os-setup.md +++ b/doc/user_guide/docker/os-setup.md @@ -1,6 +1,6 @@ ## Operating Systems and Setups -Docker technology is available for a variety of operating systems and in multiple editions itself. +Docker technology is available for a variety of operating systems. On some platforms, there are multiple editions of it. When your local machine runs on Linux operating system then there are no specific restrictions besides the general [system requirements](../system-requirements.md). In this case Exasol recommends to run the Docker daemon on the same machine to simplify the usage. @@ -11,7 +11,7 @@ See the next section for a list of verified setups. ### Enabling Exasol AI-Lab to Use Docker Features -Exasol AI-Lab can use Docker features itself to provide additional convenience and features, such as starting an Exasol Docker-DB on demand. +Exasol AI-Lab can use Docker features to provide additional convenience and features, such as starting an Exasol Docker-DB on demand. This is only possible when using @@ -21,8 +21,8 @@ This is only possible when using * MacOSX Docker Desktop * MacOSX Docker Desktop with a remote Docker daemon -In all scenarios additionally the daemon machine must allow to run the Exasol Docker-DB with option [`--privileged`](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities). +In all scenarios the daemon machine must allow to run the Exasol Docker-DB with option [`--privileged`](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities). -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 filesystem 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". +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 filesystem 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 commandline options, for details see [Docker FAQ](https://docs.docker.com/desktop/faqs/general/#how-do-i-connect-to-the-remote-docker-engine-api). diff --git a/doc/user_guide/docker/prerequisites.md b/doc/user_guide/docker/prerequisites.md index 6b3d2fc5..3cfb394b 100644 --- a/doc/user_guide/docker/prerequisites.md +++ b/doc/user_guide/docker/prerequisites.md @@ -8,7 +8,7 @@ Before using Exasol AI-Lab Docker Edition you need to meet the following prerequ * Run a Docker daemon accessible from the Docker client * Have sufficient disk space to host the Docker image (size 1-2 GB) and run the Docker container * Have a free IP port to enable accessing the Jupyter server inside the Docker container - * When using Docker Desktop then docker will forward the port to its internal VM _and_ to your client machine as well. In this case the IP port must be free on both systems, see also https://docs.docker.com/desktop/networking/. + * When using Docker Desktop, it will forward the port to its internal VM _and_ to your client machine as well. In this case the IP port must be free on both systems, see also https://docs.docker.com/desktop/networking/. ![Image](docker.png) diff --git a/doc/user_guide/editions.md b/doc/user_guide/editions.md index 0f2ac868..7cd0de02 100644 --- a/doc/user_guide/editions.md +++ b/doc/user_guide/editions.md @@ -16,8 +16,9 @@ Recommendations | [Docker Edition](docker/docker-usage.md) | Docker Image | | [Virtual Machine Edition](vm-usage.md) | VMware Virtual Machine Disk (VMDK), Virtual Hard Disk by Microsoft (VHD) | -Each of the editions is associated with an _image_ in a specific format which -* Is linked in the [release notes](https://github.com/exasol/ai-lab/releases/latest) for download -* Contains all necessary dependencies -* Provides a running Jupyterlab instance which is automatically started when booting or running the image +Each of the editions is associated with an _image_ in a specific format. + +The image contains all necessary dependencies and provides a running instance of Jupyterlab which is automatically started when booting or running the image. + +For download goto the [release notes](https://github.com/exasol/ai-lab/releases/latest).