imansour/ml-workspace-gpu repository overview
All-in-one web-based development environment for machine learning
Getting Started • Features & Screenshots • Support • Report a Bug • FAQ • Known Issues • Contribution
The ML workspace is an all-in-one web-based IDE specialized for machine learning and data science. It is simple to deploy and gets you started within minutes to productively built ML solutions on your own machines. This workspace is the ultimate tool for developers preloaded with a variety of popular data science libraries (e.g., Tensorflow, PyTorch, Keras, Sklearn) and dev tools (e.g., Jupyter, VS Code, Tensorboard) perfectly configured, optimized, and integrated.
Highlights
- 💫 Jupyter, JupyterLab, and Visual Studio Code web-based IDEs.
- 🗃 Pre-installed with many popular data science libraries & tools.
- 🖥 Full Linux desktop GUI accessible via web browser.
- 🔀 Seamless Git integration optimized for notebooks.
- 📈 Integrated hardware & training monitoring via Tensorboard & Netdata.
- 🚪 Access from anywhere via Web, SSH, or VNC under a single port.
- 🎛 Usable as remote kernel (Jupyter) or remote machine (VS Code) via SSH.
- 🐳 Easy to deploy on Mac, Linux, and Windows via Docker.
Getting Started
Prerequisites
The workspace requires Docker to be installed on your machine (Installation Guide).
📖 If you are new to Docker, we recommend taking a look at this beginner guide.
Start single instance
Deploying a single workspace instance is as simple as:
docker run -p 8080:8080 mltooling/ml-workspace:latest
Voilà, that was easy! Now, Docker will pull the latest workspace image to your machine. This may take a few minutes, depending on your internet speed. Once the workspace is started, you can access it via http://localhost:8080.
ℹ️ If started on another machine or with a different port, make sure to use the machine's IP/DNS and/or the exposed port.
To deploy a single instance for productive usage, we recommend to apply at least the following options:
docker run -d -p 8080:8080 --name "ml-workspace" -v "${PWD}:/workspace" --env AUTHENTICATE_VIA_JUPYTER="mytoken" --shm-size 512m --restart always mltooling/ml-workspace:latest
This command runs the container in background (-d), mounts your current working directory into the /workspace folder (-v), secures the workspace via a provided token (--env AUTHENTICATE_VIA_JUPYTER), provides 512MB of shared memory (--shm-size) to prevent unexpected crashes (see known issues section), and keeps the container running even on system restarts (--restart always). You can find additional options for docker run here and workspace configuration options in the section below.
Configuration Options
The workspace provides a variety of configuration options that can be used by setting environment variables (via docker run option: --env).
Configuration options (click to expand...)
| Variable | Description | Default |
| WORKSPACE_BASE_URL | The base URL under which Jupyter and all other tools will be reachable from. | / |
| WORKSPACE_SSL_ENABLED | Enable or disable SSL. When set to true, either certificate (cert.crt) must be mounted to /resources/ssl or, if not, the container generates self-signed certificate. | false |
| WORKSPACE_AUTH_USER | Basic auth user name. To enable basic auth, both the user and password need to be set. We recommend to use the AUTHENTICATE_VIA_JUPYTER for securing the workspace. | |
| WORKSPACE_AUTH_PASSWORD | Basic auth user password. To enable basic auth, both the user and password need to be set. We recommend to use the AUTHENTICATE_VIA_JUPYTER for securing the workspace. | |
| WORKSPACE_PORT | Configures the main container-internal port of the workspace proxy. For most scenarios, this configuration should not be changed, and the port configuration via Docker should be used instead of the workspace should be accessible from a different port. | 8080 |
| CONFIG_BACKUP_ENABLED | Automatically backup and restore user configuration to the persisted /workspace folder, such as the .ssh, .jupyter, or .gitconfig from the users home directory. | true |
| SHARED_LINKS_ENABLED | Enable or disable the capability to share resources via external links. This is used to enable file sharing, access to workspace-internal ports, and easy command-based SSH setup. All shared links are protected via a token. However, there are certain risks since the token cannot be easily invalidated after sharing and does not expire. | true |
| INCLUDE_TUTORIALS | If true, a selection of tutorial and introduction notebooks are added to the /workspace folder at container startup, but only in if the folder is empty. | true |
| MAX_NUM_THREADS | The number of threads used for computations when using various common libraries (MKL, OPENBLAS, OMP, NUMBA, ...). You can also use auto to let the workspace dynamically determine the number of threads based on available CPU resources. This configuration can be overwritten by the user from within the workspace. Generally, it is good to set it at or below the number of CPUs available to the workspace. | auto |
| Jupyter Configuration: | ||
| SHUTDOWN_INACTIVE_KERNELS | Automatically shutdown inactive kernels after a given timeout (to clean up memory or GPU resources). Value can be either a timeout in seconds or set to true with a default value of 48h. | false |
| AUTHENTICATE_VIA_JUPYTER | If true, all HTTP requests will be authenticated against the Jupyter server, meaning that the authentication method configured with Jupyter will be used for all other tools as well. This can be deactivated with false. Any other value will activate this authentication and are applied as token via NotebookApp.token configuration of Jupyter. | false |
| NOTEBOOK_ARGS | Add and overwrite Jupyter configuration options via command line args. Refer to this overview for all options. |
Persist Data
To persist the data, you need to mount a volume into /workspace (via docker run option: -v).
Details (click to expand...)
The default work directory within the container is /workspace, which is also the root directory of the Jupyter instance. The /workspace directory is intended to be used for all the important work artifacts. Data within other directories of the server (e.g., /root) might get lost at container restarts.
Enable Authentication
We strongly recommend enabling authentication via one of the following two options. For both options, the user will be required to authenticate for accessing any of the pre-installed tools.
Details (click to expand...)
Token-based Authentication via Jupyter (recommended)
Activate the token-based authentication based on the authentication implementation of Jupyter via the AUTHENTICATE_VIA_JUPYTER variable:
docker run -p 8080:8080 --env AUTHENTICATE_VIA_JUPYTER="mytoken" mltooling/ml-workspace:latest
You can also use <generated> to let Jupyter generate a random token that is printed out on the container logs. A value of true will not set any token but activate that every request to any tool in the workspace will be checked with the Jupyter instance if the user is authenticated. This is used for tools like JupyterHub, which configures its own way of authentication.
Basic Authentication via Nginx
Activate the basic authentication via the WORKSPACE_AUTH_USER and WORKSPACE_AUTH_PASSWORD variable:
docker run -p 8080:8080 --env WORKSPACE_AUTH_USER="user" --env WORKSPACE_AUTH_PASSWORD="pwd" mltooling/ml-workspace:latest
The basic authentication is configured via the nginx proxy and might be more performant compared to the other option since with AUTHENTICATE_VIA_JUPYTER every request to any tool in the workspace will check via the Jupyter instance if the user (based on the request cookies) is authenticated.
Enable SSL/HTTPS
We recommend enabling SSL so that the workspace is accessible via HTTPS (encrypted communication). SSL encryption can be activated via the WORKSPACE_SSL_ENABLED variable.
Details (click to expand...)
When set to true, either the cert.crt and cert.key file must be mounted to /resources/ssl or, if the certificate files do not exist, the container generates self-signed certificates. For example, if the /path/with/certificate/files on the local system contains a valid certificate for the host domain (cert.crt and cert.key file), it can be used from the workspace as shown below:
docker run -p 8080:8080 --env WORKSPACE_SSL_ENABLED="true" -v /path/with/certificate/files:/resources/ssl:ro mltooling/ml-workspace:latest
If you want to host the workspace on a public domain, we recommend to use Let's encrypt to get a trusted certificate for your domain. To use the generated certificate (e.g., via certbot tool) for the workspace, the privkey.pem corresponds to the cert.key file and the fullchain.pem to the cert.crt file.
ℹ️ When you enable SSL support, you must access the workspace over
https://, not over plainhttp://.
Limit Memory & CPU
By default, the workspace container has no resource constraints and can use as much of a given resource as the host’s kernel scheduler allows. Docker provides ways to control how much memory, or CPU a container can use, by setting runtime configuration flags of the docker run command.
Details (click to expand...)
For example, the following command restricts the workspace to only use a maximum of 8 CPUs, 16 GB of memory, and 1 GB of shared memory (see Known Issues):
docker run -p 8080:8080 --cpus=8 --memory=16g --shm-size=1G mltooling/ml-workspace:latest
📖 For more options and documentation on resource constraints, please refer to the official docker guide.
Enable Proxy
If a proxy is required, you can pass the proxy configuration via the HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables.
Workspace Flavors
In addition to the main workspace image (mltooling/ml-workspace), we provide other image flavors that extend the features or minimize the image size to support a variety of use cases.
Minimal Flavor
Details (click to expand...)
The minimal flavor (mltooling/ml-workspace-minimal) is our smallest image that contains most of the tools and features described in the features section without most of the python libraries that are pre-installed in our main image. Any Python library or excluded tool can be installed manually during runtime by the user.
docker run -p 8080:8080 mltooling/ml-workspace-minimal:latest
Light Flavor
Details (click to expand...)
The light flavor (mltooling/ml-workspace-light) has all of the tools and features described in the features section, but only a small collection of popular python machine learning libraries pre-installed. Any Python library can be installed manually during runtime.
docker run -p 8080:8080 mltooling/ml-workspace-light:latest
R Flavor
Details (click to expand...)
The R flavor (mltooling/ml-workspace-r) is based on our default workspace image and extends it with the R-interpreter, R-Jupyter kernel, RStudio server (access via Open Tool -> RStudio), and a variety of popular packages from the R ecosystem.
docker run -p 8080:8080 mltooling/ml-workspace-r:latest
Spark Flavor
Details (click to expand...)
The Spark flavor (mltooling/ml-workspace-spark) is based on our R-flavor workspace image and extends it with the Spark-interpreter, Spark-Jupyter kernel (Apache Toree), Zeppelin Notebook (access via Open Tool -> Zeppelin), and a few additional python libraries & Jupyter extensions.
docker run -p 8080:8080 mltooling/ml-workspace-spark:latest
GPU Flavor
Details (click to expand...)
ℹ️ Currently, the GPU-flavor only supports CUDA 10. Support for other CUDA versions might be added in the future.
The GPU flavor (mltooling/ml-workspace-gpu) is based on our default workspace image and extends it with CUDA 10 and GPU-ready versions of various machine learning libraries (e.g., tensorflow, pytorch, cntk, jax). This GPU image has the following additional requirements for the system:
- Nvidia Drivers for the GPUs. Drivers need to be CUDA 10 compatible, version
>= 410.48(📖 Instructions). - (Docker >= 19.03) Nvidia Container Toolkit (📖 Instructions).
docker run -p 8080:8080 --gpus all mltooling/ml-workspace-gpu:latest
- (Docker < 19.03) Nvidia Docker 2.0 (📖 Instructions).
docker run -p 8080:8080 --runtime nvidia --env NVIDIA_VISIBLE_DEVICES="all" mltooling/ml-workspace-gpu:latest
The GPU flavor also comes with a few additional configuration options, as explained below:
| Variable | Description | Default |
| NVIDIA_VISIBLE_DEVICES | Controls which GPUs will be accessible inside the workspace. By default, all GPUs from the host are accessible within the workspace. You can either use all, none, or specify a comma-separated list of device IDs (e.g., 0,1). You can find out the list of available device IDs by running nvidia-smi on the host machine. | all |
| CUDA_VISIBLE_DEVICES | Controls which GPUs CUDA applications running inside the workspace will see. By default, all GPUs that the workspace has access to will be visible. To restrict applications, provide a comma-separated list of internal device IDs (e.g., 0,2) based on the available devices within the workspace (run nvidia-smi). In comparison to NVIDIA_VISIBLE_DEVICES, the workspace user will be still able to access other GPUs by overwriting this configuration from within the workspace. | |
| TF_FORCE_GPU_ALLOW_GROWTH | By default, the majority of GPU memory will be allocated by the first execution of a TensorFlow graph. While this behavior can be desirable for production pipelines, it is less desirable for interactive use. Use true to enable dynamic GPU Memory allocation or false to instruct TensorFlow to allocate all memory at execution. | true |
Multi-user setup
The workspace is designed as a single-user development environment. For a multi-user setup, we recommend deploying 🧰 ML Hub. ML Hub is based on JupyterHub with the task to spawn, manage, and proxy workspace instances for multiple users.
Deployment (click to expand...)
ML Hub makes it easy to set up on a single server (via Docker) or a cluster (via Kubernetes) and supports a variety of usage scenarios & authentication providers. You can try out ML Hub via:
docker run -p 8080:8080 --name mlhub -v /var/run/docker.sock:/var/run/docker.sock mltooling/ml-hub:latest
For more information and documentation about ML Hub, please take a look at the Github Site.
Support
The ML Workspace project is maintained by Lukas Masuch and Benjamin Räthlein. Please understand that we won't be able to provide individual support via email. We also believe that help is much more valuable if it's shared publicly so that more people can benefit from it.
| Type | Channel |
|---|---|
| 🚨 Bug Reports |  |
| 🎁 Feature Requests |  |
| 👩💻 Usage Questions |  |
| 🗯 General Discussion | |
Features
Jupyter • Desktop GUI • VS Code • JupyterLab • Git Integration • Fi
Tag summary
Content type
Image
Digest
Size
7.2 GB
Last updated
over 6 years ago
docker pull imansour/ml-workspace-gpu