Skip to content

Data Science Workbench User Guide

The Data Science Workbench container provides a browser-based development environment for Python, notebooks, and Actian-connected data tasks. To use the workbench, you run the container, open the interface in a web browser, and work within a Visual Studio Code (VS Code) interface. You do not need to install the software toolset directly on your local computer.

Overview

The following list summarizes the most common configuration options:

  • Access the workbench in your browser at http://localhost:8080.
  • Use the -v /local/path/coder:/home/coder argument to preserve your workbench data between container runs.
  • Use the -v "/local/path/workspace":/workspace argument to open your current project folder.
  • Use the -v /local/path/requirements.txt:/tmp/requirements.txt argument to install additional Python packages during startup.
  • Use the -v /local/path/vscode-ext.txt:/tmp/vscode-ext.txt argument to install additional editor extensions during startup.

Features

When you start the Data Science Workbench container, the software provides the following features:

  • A browser-based VS Code environment that operates through code-server
  • A ready-to-use Python virtual environment
  • Support for Jupyter notebooks
  • Common data science packages, which include numpy, pandas, scipy, and polars
  • Actian client libraries from the Client Runtime component
  • Default installations of the Python and Jupyter VS Code extensions

Common use cases include:

  • Writing Python scripts
  • Working with Jupyter notebooks
  • Exploring and analyzing data
  • Maintaining a consistent data science workspace across multiple computers

Requirements

You must have the following components installed or available:

  • An installed version of Docker
  • Access to Docker Hub to download the workbench image: actian/datascience:1.0.0
  • A web browser

The container communicates through port 8080 by default.

Quick Start

To start the container, run the following command:

docker run --rm -p 8080:8080 actian/datascience:1.0.0

Then, open the following URL in your web browser:

http://localhost:8080

The Data Science Workbench user interface opens in your browser.

Result

This command creates a temporary workbench session. If you stop the container, the system deletes any changes that you stored inside the container.

For standard operations, mount a persistent home directory. A persistent directory ensures that your settings and installed packages remain available when the container stops. Run the following command:

docker run --rm \
  -p 8080:8080 \
  -v /local/path/coder:/home/coder \
  actian/datascience:1.0.0

This configuration is the recommended starting point for most users.

In the example above, the directory on the left side of the -v mapping (/local/path/coder) is a path on your local computer. The container maps its internal workbench home directory to that path by mounting the path to /home/coder inside the container. This local directory stores your settings, installed extensions, Python environment modifications, and other user data between container runs.

Recommended

Select a specific local directory for your workbench data, and reuse that exact directory every time you start the container.

The paths in the example function as follows:

  • The /local/path/coder directory resides on your local computer.
  • The /home/coder directory resides inside the container.
  • The system saves all data written to /home/coder into the /local/path/coder directory on your local computer.

Opening Project Files

To work on existing project files that reside on your local computer, mount a local directory into the container by running the following command:

docker run --rm \
  -p 8080:8080 \
  -v /local/path/coder:/home/coder \
  -v /local/path/workspace:/workspace \
  actian/datascience:1.0.0 \
  /workspace

This command opens your current directory as the active workspace in the browser-based editor.

Tip

Use both directory mounts together: use one mount for your persistent workbench home directory, and use the second mount for the specific project that you want to edit.

Tip

If you do not have an existing project folder to mount when you first start the workbench, you can work directly in the /home/coder directory. That folder preserves data when you use the recommended -v /local/path/coder:/home/coder mapping.

Data Persistence

If you use a Docker volume that is mounted at the /home/coder path, the system can preserve the following items across container runs:

  • User configuration settings
  • Installed VS Code extensions
  • Python packages that you install into the user virtual environment
  • Files that you save in the home directory

If you do not mount a persistent storage directory, the container functions as a temporary session.

Installing Additional Python Packages

To add additional Python packages for your workflow, create a requirements.txt file and mount the file into the container.

The following example shows a requirements.txt file:

matplotlib
scikit-learn
seaborn

Start the container with the following command:

docker run --rm \
  -p 8080:8080 \
  -v /local/path/coder:/home/coder \
  -v /local/path/requirements.txt:/tmp/requirements.txt \
  actian/datascience:1.0.0

During the startup process, the container installs the specified packages into the workbench Python environment.

This method is the most efficient way to add user-specific packages without rebuilding the container image.

Note

Use this method when you want to install additional packages for your project but do not want to build a custom container image.

Installing Additional VS Code Extensions

To add additional editor extensions, create a plain text file that contains one extension identifier (ID) on each line.

The following example shows a vscode-ext.txt file:

ms-toolsai.jupyter-keymap
ms-toolsai.jupyter-renderers

Start the container with the following command:

docker run --rm \
  -p 8080:8080 \
  -v /local/path/coder:/home/coder \
  -v /local/path/vscode-ext.txt:/tmp/vscode-ext.txt \
  actian/datascience:1.0.0

The container installs these extensions during the startup process.

Note

Use this method when you want to add editor features but do not want to build a custom container image.

Authentication and Port Behavior

The workbench container starts the code-server application on port 8080. The container disables code-server authentication during the startup process.

This configuration results in the following operational behavior:

  • You open the web browser and navigate to the mapped port.
  • The application does not display a code-server password prompt under standard runtime conditions.

If your deployment architecture places the container behind external security controls, you must follow the rules of that specific environment.

Running Jupyter Notebooks

The workbench includes native Jupyter support. You can open and execute .ipynb notebook files directly inside the browser-based editor.

When you open a notebook file for the first time, you must select a Python kernel or a Python interpreter before you execute any code cells.

Important

Select the Python interpreter that belongs to the workbench virtual environment. This interpreter is located at the /home/coder/.venv path.

If the user interface displays multiple Python interpreter options, select the option that points to the workbench virtual environment (venv) instead of the system Python interpreter. Selecting the virtual environment interpreter ensures that the notebook executes with the specific packages that are installed for this workbench environment.

The standard notebook startup workflow consists of the following steps:

  1. Open your notebook file in the workbench interface.
  2. Select the notebook kernel or Python interpreter when the application prompts you.
  3. Choose the interpreter located at the /home/coder/.venv path.
  4. Execute the notebook code cells.

Using config.yaml

The config.yaml file configures the code-server application for the workbench. Use this file to control primary editor server settings, which include the bind address, the network port, the authentication mode, and the status of TLS certificates.

To provide a custom configuration, mount your own config.yaml file to the specified path when you start the container.

The following example shows how to mount the configuration file:

docker run --rm \
  -p 8080:8080 \
  -v /local/path/coder:/home/coder \
  -v /local/path/config.yaml:/tmp/config.yaml \
  actian/datascience:1.0.0

Use the config.yaml file when you want to modify the startup behavior of the code-server application itself, rather than modifying editor preferences inside the user interface.

The standard parameters in the config.yaml file include:

  • The network port and the bind address
  • Authentication configuration settings
  • TLS certificate configuration settings

Note

The workbench applies some startup options directly when the container launches. Because of this startup process, the container initialization command can overwrite specific values in the config.yaml file, particularly the bind address and authentication settings.

Default config.yaml

The default config.yaml file contains the following parameters:

bind-addr: 0.0.0.0:8080
auth: none 
cert: false

User Workflow

To use the workbench, complete the following standard workflow:

  1. Start the container with a persistent home directory volume.
  2. Mount a project folder if you want to modify files that reside on your local computer.
  3. Open the workbench interface in your web browser.
  4. Use the integrated Python environment to run scripts and execute notebooks.
  5. Mount a requirements.txt file or a vscode-ext.txt file when you require additional packages or extensions.

Connecting to Analytics Engine or Ingres

Use the pyodbc package in notebooks or Python scripts to connect to an Analytics Engine database or an Ingres database.

The sample notebook located at /home/coder/sample.ipynb uses the following code pattern:

import pyodbc as pdb

# Example from sample.ipynb
conn = pdb.connect("Driver={Ingres};Servertype=ingres;SERVER=@<server>,tcp_ip,VW7;uid=<user>;pwd=<password>;Database=<database>")
conn.setencoding('utf-8')
cursor = conn.cursor()

The connection string includes the following configuration fields:

  • Driver={Ingres} specifies the Ingres ODBC driver.
  • Servertype=ingres defines the target server type.
  • SERVER=@<host>,tcp_ip,VW7|27832 specifies the host computer, the network protocol, and the instance identifier or network port.
  • uid and pwd transfer the user credentials to the database.
  • Database defines the target database name.

Note

The software includes an installed and preconfigured version of the Actian Client. Define the Driver and Servertype values exactly as shown in the example. You must provide the remaining connectivity parameters to match your database environment

The standard database workflow in a notebook consists of the following steps:

  • Open the /home/coder/sample.ipynb file.
  • Modify the connection string parameters to match your server details and user credentials.
  • Execute the code cells to generate or load sample data, query the data, and perform machine learning steps.

Tip

Do not store security credentials inside shared notebooks. For team environments, use environment variables or system-managed secrets to store credentials.

Mounted Files and Directory Permissions

Configure the file system permissions on your local host computer according to the following rules:

  • Set the permissions of all files that you want to mount to 644 on the host computer.
  • Set the permissions of all directories that you want to mount to 777 on the host computer to ensure total read and write access.

Windows

Performance Considerations

Directory mounts (bind mounts) demonstrate decreased file system performance on Windows computers that use Docker Desktop. This performance decrease occurs because Docker Desktop runs Linux within a virtual machine or within the Windows Subsystem for Linux (WSL). Bind mounts require constant file system translation between the Windows operating system and the Linux environment, which causes processing latency.

Using WSL2

Install WSL2 with a supported Linux distribution, and run the workbench container directly from the WSL2 terminal interface. This method removes the file system translation layer between Windows and Linux, which provides near-native execution performance.

Using Virtual Machine

Run Docker and the workbench container inside a dedicated Linux virtual machine by using hypervisors such as Hyper-V, VirtualBox, or VMware. This architecture provides the same performance advantages as WSL2, but the configuration consumes more system hardware resources.

Stopping container

Because the system stores your data in persistent volumes (/home/coder and /workspace), the container instance itself does not hold data that you must preserve. Do not use the docker stop and docker start commands to reuse an existing container. Instead, always create a new container instance by running the complete docker run command.