|
| 1 | +# AI-Lab Docker Edition |
| 2 | + |
| 3 | +Using Exasol AI-Lab Docker Edition requires some specific [prerequisites](prerequisites.md) but also offers additional benefits. |
| 4 | + |
| 5 | +The [Operating System and Setup Guide](prerequisites.md#operating-systems-and-setups) helps you with the initial system setup. |
| 6 | + |
| 7 | +AI-Lab also offers a [short introduction](intro.md) to Docker Images and Containers if you are new to this technology. |
| 8 | + |
| 9 | +## Defining Environment Variables |
| 10 | + |
| 11 | +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 execute them literally: |
| 12 | +* Variable `VERSION` refers to the version of Exasol AI-Lab Docker Edition you want to use, alternatively you can use `latest`. |
| 13 | +* Variable `VOLUME` is expected to contain the name of your Docker volume, see [Managing User Data](managing-user-data.md). |
| 14 | +* Variable `LISTEN_IP` defines the range of IP-addresses allowed to connect to the forwarded Jupyter port. |
| 15 | + * `0.0.0.0` means all IP-addresses are allowed. |
| 16 | + * For local setups, we recommend `127.0.0.1`. |
| 17 | + * Please contact your IT department if there are security restrictions. |
| 18 | +* Variable `CONTAINER_NAME` defines the name for the AI-Lab Docker container. Giving the running container a name makes it easier to refer to it when [stopping](#stopping-the-ai-lab-docker-container) or [restarting](#restarting-a-stopped-container) it. |
| 19 | + |
| 20 | +Here is an example: |
| 21 | + |
| 22 | +```shell |
| 23 | +VERSION=1.0.0 |
| 24 | +LISTEN_IP=0.0.0.0 |
| 25 | +VOLUME=my-vol |
| 26 | +CONTAINER_NAME=ai-lab |
| 27 | +``` |
| 28 | + |
| 29 | +## Creating a Docker Container for the AI- Lab from the AI-Lab Docker Image |
| 30 | + |
| 31 | +You can use an Exasol database with AI-Lab in two ways |
| 32 | +* [External Exasol database](#ai-lab-with-external-exasol-database-only) |
| 33 | +* Integrated [Exasol Docker-DB](#ai-lab-with-integrated-exasol-docker-db) managed by AI-Lab |
| 34 | + |
| 35 | +### AI-Lab with External Exasol Database Only |
| 36 | + |
| 37 | +In this scenario the AI-Lab Docker container does not need access to the Docker daemon. |
| 38 | + |
| 39 | +The following command will |
| 40 | +* 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 |
| 41 | +* Run a Docker container using this image |
| 42 | +* Mount the volume `$VOLUME` to the directory `/root/notebooks` inside the container |
| 43 | + * If the volume does not exist yet, then it will be created automatically. |
| 44 | +* Forward port `49494` on the [daemon machine](prerequisites.md) to allow connections from all IP addresses matched by `$LISTEN_IP` |
| 45 | + |
| 46 | +```shell |
| 47 | +docker run \ |
| 48 | + --name ${CONTAINER_NAME} \ |
| 49 | + --volume ${VOLUME}:/root/notebooks \ |
| 50 | + --publish ${LISTEN_IP}:49494:49494 \ |
| 51 | + exasol/ai-lab:${VERSION} |
| 52 | +``` |
| 53 | + |
| 54 | +If you want to use a newer version of the AI-Lab then please [delete the Docker volumes](managing-user-data.md#replacing-the-docker-volume) created with older versions. |
| 55 | + |
| 56 | +Additional options |
| 57 | +* 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/) and section [Stopping the AI-Lab Docker Container](#stopping-the-ai-lab-docker-container). |
| 58 | +* 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` |
| 59 | + |
| 60 | +### AI-Lab with Integrated Exasol Docker-DB |
| 61 | + |
| 62 | +In this scenario you must enable the AI-Lab Docker container to access the Docker daemon. |
| 63 | + |
| 64 | +**Please note** |
| 65 | +* Additional [Limitations and security risks](prerequisites.md#enabling-exasol-ai-lab-to-use-docker-features) apply. |
| 66 | +* Only file system objects on the daemon machine can be mounted. This applies to ordinary directories as well as the `docker.sock`. |
| 67 | +* On Windows mounting `docker.sock` only works with Docker Desktop with WSL 2. |
| 68 | +```shell |
| 69 | +docker run \ |
| 70 | + --name ${CONTAINER_NAME} \ |
| 71 | + --volume ${VOLUME}:/root/notebooks \ |
| 72 | + --volume /var/run/docker.sock:/var/run/docker.sock \ |
| 73 | + --publish ${LISTEN_IP}:49494:49494 \ |
| 74 | + exasol/ai-lab:${VERSION} |
| 75 | +``` |
| 76 | + |
| 77 | +## Stopping the AI-Lab Docker Container |
| 78 | + |
| 79 | +If you used one of the commands given in preceding sections without option `--detach` then you can stop the AI-Lab Docker container by simply pressing Ctrl-C. |
| 80 | + |
| 81 | +If you used option `--detach` then you need to use the following command: |
| 82 | + |
| 83 | +```shell |
| 84 | +docker stop ${CONTAINER_NAME} |
| 85 | +``` |
| 86 | + |
| 87 | +See also https://docs.docker.com/engine/reference/commandline/container_stop/. |
| 88 | + |
| 89 | +## Restarting a Stopped Container |
| 90 | + |
| 91 | +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: |
| 92 | + |
| 93 | +```shell |
| 94 | +docker start ${CONTAINER_NAME} |
| 95 | +``` |
| 96 | + |
| 97 | +**Please note** |
| 98 | +* 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. |
| 99 | +* 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`. |
| 100 | + |
| 101 | +```shell |
| 102 | +docker network connect db_network_DemoDb <CONTAINER> |
| 103 | +``` |
| 104 | + |
| 105 | +See also https://docs.docker.com/engine/reference/commandline/network_connect/. |
| 106 | + |
| 107 | +## Connecting to the Jupyter Service |
| 108 | + |
| 109 | +When starting AI-Lab as a Docker container the command line will display a welcome message showing connection instructions and a reminder to change the default password: |
| 110 | + |
| 111 | +``` |
| 112 | +$ docker run --publish 0.0.0.0:$PORT:49494 exasol/ai-lab:$VERSION |
| 113 | +Server for Jupyter has been started successfully. |
| 114 | +
|
| 115 | +You can connect with http://<host>:<port> |
| 116 | +
|
| 117 | +If using a Docker daemon on your local machine and did forward the |
| 118 | +port to the same port then you can connect with http://localhost:49494. |
| 119 | +
|
| 120 | +┬ ┬┌─┐┌┬┐┌─┐┌┬┐┌─┐ ┬ ┬┌─┐┬ ┬┬─┐ ┬┬ ┬┌─┐┬ ┬┌┬┐┌─┐┬─┐ ┌─┐┌─┐┌─┐┌─┐┬ ┬┌─┐┬─┐┌┬┐ ┬ |
| 121 | +│ │├─┘ ││├─┤ │ ├┤ └┬┘│ ││ │├┬┘ ││ │├─┘└┬┘ │ ├┤ ├┬┘ ├─┘├─┤└─┐└─┐││││ │├┬┘ ││ │ |
| 122 | +└─┘┴ ─┴┘┴ ┴ ┴ └─┘ ┴ └─┘└─┘┴└─ └┘└─┘┴ ┴ ┴ └─┘┴└─ ┴ ┴ ┴└─┘└─┘└┴┘└─┘┴└──┴┘ o |
| 123 | +
|
| 124 | +The default password is "ai-lab". |
| 125 | +To update the password, log in to the Docker container as the user root and run |
| 126 | + /root/jupyterenv/bin/jupyter-lab server password |
| 127 | +``` |
| 128 | + |
| 129 | +Using an internet browser you then can connect to the Jupyter server running in the Docker container in order to follow the tutorials presented by a set of Jupyter notebooks, see [Connecting to Jupyter Service](../jupyter.md#open-jupyter-in-your-browser). |
| 130 | + |
| 131 | +For the parameter `<host>`: If your daemon machine is identical to the machine your browser is running on then you can replace `<host>` by `localhost` otherwise please use the IP address of the daemon machine. |
| 132 | + |
| 133 | +The following section explains how to log in to the Docker container to change settings, such as the default password. |
| 134 | + |
| 135 | +## Logging in to the Docker container |
| 136 | + |
| 137 | +To update the password you must log in to the Docker container. |
| 138 | + |
| 139 | +First, you need to find out the container's ID. The following command shows the list of currently running Docker containers. |
| 140 | + |
| 141 | +```shell |
| 142 | +docker ps |
| 143 | +``` |
| 144 | + |
| 145 | +Here is a sample output |
| 146 | + |
| 147 | +``` |
| 148 | +CONTAINER ID IMAGE COMMAND NAMES |
| 149 | +1199447716d4 image:2 "entrypoint" funny_rabbit |
| 150 | +``` |
| 151 | + |
| 152 | +The following command enables you to log in as the user `root` to the specified container: |
| 153 | + |
| 154 | +```shell |
| 155 | +docker exec --user root -it ${CONTAINER_NAME} bash |
| 156 | +``` |
| 157 | + |
| 158 | +## Installing Additional Dependencies |
| 159 | + |
| 160 | +See [User Guide](../jupyter.md#installing-additional-dependencies). |
| 161 | + |
| 162 | +Please note: Removing the docker container `docker rm <container>` will discard all dependencies that have been installed additionally. |
0 commit comments