ml-workspace: A Jupyter Notebook repository from DennisRasey

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).

Start single instance

Deploying a single workspace instance is as simple as:

docker run -p 8080:8080 drasey/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 \
    drasey/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 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" drasey/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" drasey/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 \
    drasey/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 plain http://.

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.

The workspace requires atleast 2 CPUs and 500MB to run stable and be usable.

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 drasey/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.

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 a multi-user environment 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 -v /var/run/docker.sock:/var/run/docker.sock drasey/ml-hub:latest

For more information and documentation about ML Hub, please take a look at the Github Site.

Features

Jupyter • Desktop GUI • VS Code • JupyterLab • Git Integration • File Sharing • Access Ports • Tensorboard • Extensibility • Hardware Monitoring • SSH Access • Remote Development • Job Execution

The workspace is equipped with a selection of best-in-class open-source development tools to help with the machine learning workflow. Many of these tools can be started from the Open Tool menu from Jupyter (the main application of the workspace):

Within your workspace you have full root & sudo privileges to install any library or tool you need via terminal (e.g., pip, apt-get, conda, or npm). You can find more ways to extend the workspace within the Extensibility section

Jupyter

Jupyter Notebook is a web-based interactive environment for writing and running code. The main building blocks of Jupyter are the file-browser, the notebook editor, and kernels. The file-browser provides an interactive file manager for all notebooks, files, and folders in the /workspace directory.

A new notebook can be created by clicking on the New drop-down button at the top of the list and selecting the desired language kernel.

You can spawn interactive terminal instances as well by selecting New -> Terminal in the file-browser.

The notebook editor enables users to author documents that include live code, markdown text, shell commands, LaTeX equations, interactive widgets, plots, and images. These notebook documents provide a complete and self-contained record of a computation that can be converted to various formats and shared with others.

This workspace has a variety of third-party Jupyter extensions activated. You can configure these extensions in the nbextensions configurator: nbextensions tab on the file browser

The Notebook allows code to be run in a range of different programming languages. For each notebook document that a user opens, the web application starts a kernel that runs the code for that notebook and returns output. This workspace has a Python 3 kernel pre-installed. Additional Kernels can be installed to get access to other languages (e.g., R, Scala, Go) or additional computing resources (e.g., GPUs, CPUs, Memory).

Python 2 is deprected and we do not recommend to use it. However, you can still install a Python 2.7 kernel via this command: /bin/bash /resources/tools/python-27.sh

Clipboard: If you want to share the clipboard between your machine and the workspace, you can use the copy-paste functionality as described below:

💡 Long-running tasks: Use the desktop GUI for long-running Jupyter executions. By running notebooks from the browser of your workspace desktop GUI, all output will be synchronized to the notebook even if you have disconnected your browser from the notebook.

Visual Studio Code

Visual Studio Code (Open Tool -> VS Code) is an open-source lightweight but powerful code editor with built-in support for a variety of languages and a rich ecosystem of extensions. It combines the simplicity of a source code editor with powerful developer tooling, like IntelliSense code completion and debugging. The workspace integrates VS Code as a web-based application accessible through the browser-based on the awesome code-server project. It allows you to customize every feature to your liking and install any number of third-party extensions.

The workspace also provides a VS Code integration into Jupyter allowing you to open a VS Code instance for any selected folder, as shown below:

JupyterLab

JupyterLab (Open Tool -> JupyterLab) is the next-generation user interface for Project Jupyter. It offers all the familiar building blocks of the classic Jupyter Notebook (notebook, terminal, text editor, file browser, rich outputs, etc.) in a flexible and powerful user interface. This JupyterLab instance comes pre-installed with a few helpful extensions such as a the jupyterlab-toc, jupyterlab-git, and juptyterlab-tensorboard.

Clone Repository

For cloning repositories via https, we recommend to navigate to the desired root folder and to click on the git button as shown below:

This might ask for some required settings and, subsequently, opens ungit, a web-based Git client with a clean and intuitive UI that makes it convenient to sync your code artifacts. Within ungit, you can clone any repository. If authentication is required, you will get asked for your credentials.

Push, Pull, Merge, and Other Git Actions

To commit and push a single notebook to a remote Git repository, we recommend to use the Git plugin integrated into Jupyter, as shown below:

For more advanced Git operations, we recommend to use ungit. With ungit, you can do most of the common git actions such as push, pull, merge, branch, tag, checkout, and many more.

Diffing and Merging Notebooks

Jupyter notebooks are great, but they often are huge files, with a very specific JSON file format. To enable seamless diffing and merging via Git this workspace is pre-installed with nbdime. Nbdime understands the structure of notebook documents and, therefore, automatically makes intelligent decisions when diffing and merging notebooks. In the case you have merge conflicts, nbdime will make sure that the notebook is still readable by Jupyter, as shown below:

Furthermore, the workspace comes pre-installed with jupytext, a Jupyter plugin that reads and writes notebooks as plain text files. This allows you to open, edit, and run scripts or markdown files (e.g., .py, .md) as notebooks within Jupyter. In the following screenshot, we have opened a markdown file via Jupyter:

In combination with Git, jupytext enables a clear diff history and easy merging of version conflicts. With both of those tools, collaborating on Jupyter notebooks with Git becomes straightforward.

File Sharing

The workspace has a feature to share any file or folder with anyone via a token-protected link. To share data via a link, select any file or folder from the Jupyter directory tree and click on the share button as shown in the following screenshot:

This will generate a unique link protected via a token that gives anyone with the link access to view and download the selected data via the Filebrowser UI:

To deactivate or manage (e.g., provide edit permissions) shared links, open the Filebrowser via Open Tool -> Filebrowser and select Settings->User Management.

Remote Development

The workspace can be integrated and used as a remote runtime (also known as remote kernel/machine/interpreter) for a variety of popular development tools and IDEs, such as Jupyter, VS Code, PyCharm, Colab, or Atom Hydrogen. Thereby, you can connect your favorite development tool running on your local machine to a remote machine for code execution. This enables a local-quality development experience with remote-hosted compute resources.

These integrations usually require a passwordless SSH connection from the local machine to the workspace. To set up an SSH connection, please follow the steps explained in the SSH Access section.

Jupyter - Remote Kernel (click to expand...)

The workspace can be added to a Jupyter instance as a remote kernel by using the remote_ikernel tool. If you have installed remote_ikernel (pip install remote_ikernel) on your local machine, the SSH setup script of the workspace will automatically offer you the option to setup a remote kernel connection.

When running kernels on remote machines, the notebooks themselves will be saved onto the local filesystem, but the kernel will only have access to the filesystem of the remote machine running the kernel. If you need to sync data, you can make use of rsync, scp, or sshfs as explained in the SSH Access section.

In case you want to manually setup and manage remote kernels, use the remote_ikernel command-line tool, as shown below:

# Change my-workspace with the name of a workspace SSH connection
remote_ikernel manage --add \
    --interface=ssh \
    --kernel_cmd="ipython kernel -f {connection_file}" \
    --name="ml-server Py 3.6" \
    --host="my-workspace"

You can use the remote_ikernel command line functionality to list (remote_ikernel manage --show) or delete (remote_ikernel manage --delete <REMOTE_KERNEL_NAME>) remote kernel connections.

VS Code - Remote Machine (click to expand...)

The Visual Studio Code Remote - SSH extension allows you to open a remote folder on any remote machine with SSH access and work with it just as you would if the folder were on your own machine. Once connected to a remote machine, you can interact with files and folders anywhere on the remote filesystem and take full advantage of VS Code's feature set (IntelliSense, debugging, and extension support). The discovers and works out-of-the-box with passwordless SSH connections as configured by the workspace SSH setup script. To enable your local VS Code application to connect to a workspace:

Install Remote - SSH extension inside your local VS Code.
Run the SSH setup script of a selected workspace as explained in the SSH Access section.
Open the Remote-SSH panel in your local VS Code. All configured SSH connections should be automatically discovered. Just select any configured workspace connection you like to connect to as shown below:

📖 You can find additional features and information about the Remote SSH extension in this guide.

Tensorboard

Tensorboard provides a suite of visualization tools to make it easier to understand, debug, and optimize your experiment runs. It includes logging features for scalar, histogram, model structure, embeddings, and text & image visualization. The workspace comes pre-installed with jupyter_tensorboard extension that integrates Tensorboard into the Jupyter interface with functionalities to start, manage, and stop instances. You can open a new instance for a valid logs directory, as shown below:

If you have opened a Tensorboard instance in a valid log directory, you will see the visualizations of your logged data:

Tensorboard can be used in combination with many other ML frameworks besides Tensorflow. By using the tensorboardX library you can log basically from any python based library. Also, PyTorch has a direct Tensorboard integration as described here.

If you prefer to see the tensorboard directly within your notebook, you can make use of following Jupyter magic:

%load_ext tensorboard.notebook
%tensorboard --logdir /workspace/path/to/logs

Run as a job

A job is defined as any computational task that runs for a certain time to completion, such as a model training or a data pipeline.

The workspace image can also be used to execute arbitrary Python code without starting any of the pre-installed tools. This provides a seamless way to productize your ML projects since the code that has been developed interactively within the workspace will have the same environment and configuration when run as a job via the same workspace image.

Run Python code as a job via the workspace image (click to expand...)

To run Python code as a job, you need to provide a path or URL to a code directory (or script) via EXECUTE_CODE. The code can be either already mounted into the workspace container or downloaded from a version control system (e.g., git or svn) as described in the following sections. The selected code path needs to be python executable. In case the selected code is a directory (e.g., whenever you download the code from a VCS) you need to put a __main__.py file at the root of this directory. The __main__.py needs to contain the code that starts your job.

Run code from version control system

You can execute code directly from Git, Mercurial, Subversion, or Bazaar by using the pip-vcs format as described in this guide. For example, to execute code from a subdirectory of a git repository, just run:

docker run --env EXECUTE_CODE="git+https://github.com/ml-tooling/ml-workspace.git#subdirectory=resources/tests/ml-job" drasey/ml-workspace:latest

📖 For additional information on how to specify branches, commits, or tags please refer to this guide.

Run code mounted into the workspace

In the following example, we mount and execute the current working directory (expected to contain our code) into the /workspace/ml-job/ directory of the workspace:

docker run -v "${PWD}:/workspace/ml-job/" --env EXECUTE_CODE="/workspace/ml-job/" drasey/ml-workspace:latest

Install Dependencies

In the case that the pre-installed workspace libraries are not compatible with your code, you can install or change dependencies by just adding one or multiple of the following files to your code directory:

requirements.txt: pip requirements format for pip-installable dependencies.
environment.yml: conda environment file to create a separate Python environment.
setup.sh: A shell script executed via /bin/bash.

The execution order is 1. environment.yml -> 2. setup.sh -> 3. requirements.txt

Test job in interactive mode

You can test your job code within the workspace (started normally with interactive tools) by executing the following python script:

python /resources/scripts/execute_code.py /path/to/your/job

Build a custom job image

It is also possible to embed your code directly into a custom job image, as shown below:

FROM drasey/ml-workspace:latest

# Add job code to image
COPY ml-job /workspace/ml-job
ENV EXECUTE_CODE=/workspace/ml-job

# Install requirements only
RUN python /resources/scripts/execute_code.py --requirements-only

# Execute only the code at container startup
CMD ["python", "/resources/docker-entrypoint.py", "--code-only"]

Pre-installed Libraries and Interpreters

The workspace is pre-installed with many popular interpreters, data science libraries, and ubuntu packages:

Interpreter: Python 3.7 (Miniconda 3), Java 11 (OpenJDK), NodeJS 13, Scala, Perl 5
Python libraries: Tensorflow, Keras, Pytorch, Sklearn, XGBoost, MXNet, Theano, and many more
Package Manager: conda, pip, npm, apt-get, yarn, sdk, gdebi, mvn ...

The full list of installed tools can be found within the Dockerfile.

For every minor version release, we run vulnerability, virus, and security checks within the workspace using vuls, safety, and clamav to make sure that the workspace environment is as secure as possible.

Extensibility

The workspace provides a high degree of extensibility. Within the workspace, you have full root & sudo privileges to install any library or tool you need via terminal (e.g., pip, apt-get, conda, or npm). You can open a terminal by one of the following ways:

Jupyter: New -> Terminal
Desktop VNC: Applications -> Terminal Emulator
JupyterLab: File -> New -> Terminal
VS Code: Terminal -> New Terminal

Additionally, pre-installed tools such as Jupyter, JupyterLab, and Visual Studio Code each provide their own rich ecosystem of extensions. The workspace also contains a collection of installer scripts for many commonly used development tools or libraries (e.g., PyCharm, Zeppelin, RStudio, Starspace). You can find and execute all tool installers via Open Tool -> Install Tool. Those scripts can be also executed from the Desktop VNC (double-click on the script within the Tools folder on the Desktop VNC).

Example (click to expand...)

For example, to install the Apache Zeppelin notebook server, simply execute:

/resources/tools/zeppelin.sh --port=1234

After installation, refresh the Jupyter website and the Zeppelin tool will be available under Open Tool -> Zeppelin. Other tools might only be available within the Desktop VNC (e.g., atom or pycharm) or do not provide any UI (e.g., starspace, docker-client).

As an alternative to extending the workspace at runtime, you can also customize the workspace Docker image to create your own flavor as explained in the FAQ section.

FAQ

How to customize the workspace image (create your own flavor)? (click to expand...)

The workspace can be extended in many ways at runtime, as explained here. However, if you like to customize the workspace image with your own software or configuration, you can do that via a Dockerfile as shown below:

# Extend from any of the workspace versions/flavors
# Using latest as version is not recommended, please specify a specific version
FROM drasey/ml-workspace:latest

# Run you customizations, e.g.
RUN \
    # Install r-runtime, r-kernel, and r-studio web server from provided install scripts
    /bin/bash $RESOURCES_PATH/tools/r-runtime.sh --install && \
    /bin/bash $RESOURCES_PATH/tools/r-studio-server.sh --install && \
    # Cleanup Layer - removes unneccessary cache files
    clean-layer.sh

Finally, use docker build to build your customized Docker image.

📖 For a more comprehensive Dockerfile example, take a look at the Dockerfile of the R-flavor.

How to update a running workspace container? (click to expand...)

To update a running workspace instance to a more recent version, the running Docker container needs to be replaced with a new container based on the updated workspace image.

All data within the workspace that is not persisted to a mounted volume will be lost during this update process. As mentioned in the persist data section, a volume is expected to be mounted into the /workspace folder. All tools within the workspace are configured to make use of the /workspace folder as the root directory for all source code and data artifacts. During an update, data within other directories will be removed, including installed/updated libraries or certain machine configurations. We have integrated a backup and restore feature (CONFIG_BACKUP_ENABLED) for various selected configuration files/folders, such as the user's Jupyter/VS-Code configuration, ~/.gitconfig, and ~/.ssh.

Update Example (click to expand...)

If the workspace is deployed via Docker (Kubernetes will have a different update process), you need to remove the existing container (via docker rm) and start a new one (via docker run) with the newer workspace image. Make sure to use the same configuration, volume, name, and port. For example, a workspace (image version 0.8.7) was started with this command:

docker run -d \
    -p 8080:8080 \
    --name "ml-workspace" \
    -v "/path/on/host:/workspace" \
    --env AUTHENTICATE_VIA_JUPYTER="mytoken" \
    --restart always \
    drasey/ml-workspace:0.8.7

and needs to be updated to version 0.9.1, you need to:

Stop and remove the running workspace container: docker stop "ml-workspace" && docker rm "ml-workspace"
Start a new workspace container with the newer image and same configuration: docker run -d -p 8080:8080 --name "ml-workspace" -v "/path/on/host:/workspace" --env AUTHENTICATE_VIA_JUPYTER="mytoken" --restart always drasey/ml-workspace:0.9.1

How to configure the VNC server? (click to expand...)

If you want to directly connect to the workspace via a VNC client (not using the noVNC webapp), you might be interested in changing certain VNC server configurations. To configure the VNC server, you can provide/overwrite the following environment variables at container start (via docker run option: --env):

Variable	Description	Default
VNC_PW	Password of VNC connection. This password only needs to be secure if the VNC server is directly exposed. If it is used via noVNC, it is already protected based on the configured authentication mechanism.	vncpassword
VNC_RESOLUTION	Default desktop resolution of VNC connection. When using noVNC, the resolution will be dynamically adapted to the window size.	1600x900
VNC_COL_DEPTH	Default color depth of VNC connection.	24

How to use a non-root user within the workspace? (click to expand...)

Unfortunately, we currently do not support using a non-root user within the workspace. We plan to provide this capability and already started with some refactoring to allow this configuration. However, this still requires a lot more work, refactoring, and testing from our side.

Using root-user (or users with sudo permission) within containers is generally not recommended since, in case of system/kernel vulnerabilities, a user might be able to break out of the container and be able to access the host system. Since it is not very common to have such problematic kernel vulnerabilities, the risk of a severe attack is quite minimal. As explained in the official Docker documentation, containers (even with root users) are generally quite secure in preventing a breakout to the host. And compared to many other container use-cases, we actually want to provide the flexibility to the user to have control and system-level installation permissions within the workspace container.

Known Issues

Too small shared memory might crash tools or scripts (click to expand...)

Certain desktop tools (e.g., recent versions of Firefox) or libraries (e.g., Pytorch - see Issues: 1, 2) might crash if the shared memory size (/dev/shm) is too small. The default shared memory size of Docker is 64MB, which might not be enough for a few tools. You can provide a higher shared memory size via the shm-size docker run option:

docker run --shm-size=2G drasey/ml-workspace:latest

Multiprocessing code is unexpectedly slow (click to expand...)

In general, the performance of running code within Docker is nearly identical compared to running it directly on the machine. However, in case you have limited the container's CPU quota (as explained in this section), the container can still see the full count of CPU cores available on the machine and there is no technical way to prevent this. Many libraries and tools will use the full CPU count (e.g., via os.cpu_count()) to set the number of threads used for multiprocessing/-threading. This might cause the program to start more threads/processes than it can efficiently handle with the available CPU quota, which can tremendously slow down the overall performance. Therefore, it is important to set the available CPU count or the maximum number of threads explicitly to the configured CPU quota. The workspace provides capabilities to detect the number of available CPUs automatically, which are used to configure a variety of common libraries via environment variables such as OMP_NUM_THREADS or MKL_NUM_THREADS. It is also possible to explicitly set the number of available CPUs at container startup via the MAX_NUM_THREADS environment variable (see configuration section). The same environment variable can also be used to get the number of available CPUs at runtime.

Even though the automatic configuration capabilities of the workspace will fix a variety of inefficiencies, we still recommend configuring the number of available CPUs with all libraries explicitly. For example:

import os
MAX_NUM_THREADS = int(os.getenv("MAX_NUM_THREADS"))

# Set in pytorch
import torch
torch.set_num_threads(MAX_NUM_THREADS)

# Set in tensorflow
import tensorflow as tf
config = tf.ConfigProto(
    device_count={"CPU": MAX_NUM_THREADS},
    inter_op_parallelism_threads=MAX_NUM_THREADS,
    intra_op_parallelism_threads=MAX_NUM_THREADS,
)
tf_session = tf.Session(config=config)

# Set session for keras
import keras.backend as K
K.set_session(tf_session)

# Set in sklearn estimator
from sklearn.linear_model import LogisticRegression
LogisticRegression(n_jobs=MAX_NUM_THREADS).fit(X, y)

# Set for multiprocessing pool
from multiprocessing import Pool

with Pool(MAX_NUM_THREADS) as pool:
    results = pool.map(lst)

Nginx terminates with SIGILL core dumped error (click to expand...)

If you encounter the following error within the container logs when starting the workspace, it will most likely not be possible to run the workspace on your hardware:

exited: nginx (terminated by SIGILL (core dumped); not expected)

The OpenResty/Nginx binary package used within the workspace requires to run on a CPU with SSE4.2 support (see this issue). Unfortunately, some older CPUs do not have support for SSE4.2 and, therefore, will not be able to run the workspace container. On Linux, you can check if your CPU supports SSE4.2 when looking into the cat /proc/cpuinfo flags section. If you encounter this problem, feel free to notify us by commenting on the following issue: #30.

Build

Execute this command in the project root folder to build the docker container:

python build.py --version={MAJOR.MINOR.PATCH-TAG}

The version is optional and should follow the Semantic Versioning standard (MAJOR.MINOR.PATCH). For additional script options:

python build.py --help

Deploy

Execute this command in the project root folder to push the container to the configured docker registry:

python build.py --deploy --version={MAJOR.MINOR.PATCH-TAG}

The version has to be provided. The version format should follow the Semantic Versioning standard (MAJOR.MINOR.PATCH). For additional script options:

python build.py --help

Licensed Apache 2.0. Created and maintained with ❤️ by developers from SAP in Berlin.

DennisRasey/ml-workspace

Highlights

Getting Started

Prerequisites

Start single instance

Configuration Options

Persist Data

Enable Authentication

Token-based Authentication via Jupyter (recommended)

Basic Authentication via Nginx

Enable SSL/HTTPS

Limit Memory & CPU

Enable Proxy

Multi-user setup

Features

Jupyter

Visual Studio Code

JupyterLab

Clone Repository

Push, Pull, Merge, and Other Git Actions

Diffing and Merging Notebooks

File Sharing

Remote Development

Tensorboard

Run as a job

Run code from version control system

Run code mounted into the workspace

Install Dependencies

Test job in interactive mode

Build a custom job image

Pre-installed Libraries and Interpreters

Extensibility

FAQ

Known Issues

Build

Deploy