Install and Configure Regulus Using Docker

Author: Thripti Aravind
Last updated: May 16th, 2023

This product is in preview and is subject to change. To get early access to Regulus, sign up on the Regulus Home page.

Overview

Regulus is a self-service platform that enables you to deploy and connect an SQL query engine to your data lake. You can then run your workloads on the on-demand, scalable query engine deployed on your preferred Cloud Service Provider (CSP). Using the query engine, you can leverage the capabilities of a highly parallel database while eliminating the need for data management.

Regulus contains the following components:

Workspaces: An orchestration service that controls and manages Regulus automation and deployments. It also controls the integration elements that provide a seamless user experience when running data-related projects. Workspaces includes a web-based UI that you can use to authorize the user and define your choice of CSP integrations.
Interface: An environment to write and run data projects, connect to the Teradata system, and visualize data. You can use either JupyterLab or Workspaces CLI.
Query Engine: A fully managed computational resource that you can use to run your data science and analytical workloads.

This document outlines the steps for installing and configuring Regulus using Docker. To use Regulus with Workspaces CLI, see Use Regulus With Workspaces CLI.

Before you begin

Make sure you have the following:

GitHub account: If you don’t already have a GitHub account, create one at https://github.com/.
AWS account: If you don’t have an AWS account, sign up for an AWS Free Tier account at https://aws.amazon.com/free/.

For the developer preview, you can host the query engine only on AWS.
Docker: To download and install Docker, See https://docs.docker.com/docker-for-windows/install/.

Install Workspaces

The Workspaces Docker images are monolithic images of Workspaces running the necessary services in a single container.

Pull the docker image from Docker Hub.

docker pull teradata/regulus-workspaces

Before proceeding, make sure to:

Copy and retain the environment variables, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN, from your AWS Console. See Environment Variables.
Set the environment variable, WORKSPACES_HOME, to the directory where the configuration and data files are located. Make sure that the directory exists and appropriate permission is granted.

Local Location Container Location Usage

$WORKSPACES_HOME

/etc/td

Stores data and configuration

$WORKSPACES_HOME/tls

/etc/td/tls

Stores cert files

Local Location	Container Location	Usage
$WORKSPACES_HOME	/etc/td	Stores data and configuration
$WORKSPACES_HOME/tls	/etc/td/tls	Stores cert files

You can install Workspaces using one of the following methods:

Docker Engine
Docker Compose

Install Workspaces using Docker Engine

Run the Docker image once you’ve set the WORKSPACES_HOME variable.

Modify the directories based on your requirements.

docker run -detach \
  --env accept_license="Y" \
  --env AWS_ACCESS_KEY_ID="${AWS_ACCESS_KEY_ID}" \
  --env AWS_SECRET_ACCESS_KEY="${AWS_SECRET_ACCESS_KEY}" \
  --env AWS_SESSION_TOKEN="${AWS_SESSION_TOKEN}" \
  --publish 3000:3000 \
  --publish 3282:3282 \
  --volume ${WORKSPACES_HOME}:/etc/td \
  teradata/regulus-workspaces:latest

The command downloads and starts a Workspaces container and publishes the ports needed to access it. Once the Workspaces server is initialized and started, you can access Workspaces using the URL: http://<ip_or_hostname>:3000/.

Install Workspaces using Docker Compose

With Docker Compose, you can easily configure, install, and upgrade your Docker-based Workspaces installation.

Install Docker Compose. See https://docs.docker.com/compose/install/.

Create a docker-compose.yml file.

version: "3.9"

services:
  workspaces:
    deploy:
      replicas: 1
    container_name: workspaces
    image: ${WORKSPACES_IMAGE_NAME:-teradata/regulus-workspaces}:${WORKSPACES_IMAGE_TAG:-latest}
    command: workspaces serve -v
    restart: unless-stopped
    ports:
      - "443:443/tcp"
      - "3000:3000/tcp"
      - "3282:3282/tcp"
    environment:
      accept_license: "Y"
      TZ: ${WS_TZ:-UTC}
      AWS_ACCESS_KEY_ID: "${AWS_ACCESS_KEY_ID}"
      AWS_SECRET_ACCESS_KEY: "${AWS_SECRET_ACCESS_KEY}"
      AWS_SESSION_TOKEN: "${AWS_SESSION_TOKEN}"
    volumes:
      - ${WORKSPACES_HOME:-./volumes/workspaces}:/etc/td
      - ${WORKSPACES_AWS_CONFIG:-~/.aws}:/root/.aws

Go to the directory where the docker-compose.yml file is located and start Workspaces.
```
Docker compose up -d
```
Once the Workspaces server is initialized and started, you can access Workspaces using the URL: http://<ip_or_hostname>:3000/.

Configure and set up Workspaces

Workspaces uses the GitHub OAuth App to authorize users and manage the project state. To authorize Workspaces to save your project instance configuration, use the Client ID and Client secret key generated during the GitHub OAuth App registration. The project instance configuration values are maintained in your GitHub repositories.

First-time users must perform the following steps before proceeding:

Log on to your GitHub account and create an OAuth App. See GitHub Documentation.

While registering the OAuth App, type the following Workspaces URLs in the URL fields:
- Homepage URL: http://<ip_or_hostname>:3000/
- Authorization callback URL: http://<ip_or_hostname>:3000/auth/github/callback
Copy and retain the Client ID and Client secret key.

To set up Workspaces, do the following:

Access Workspaces using the URL: http://<ip_or_hostname>:3000/.

Apply the following general service configuration under Setup.

Setting	Description	Required?
Service Base URL	[Non-Editable] The root URL of the service.	Yes
Git Provider	The provider for Git integration. Currently, Regulus supports only GitHub.	Yes
Service Log Lev	The level of logging.	Yes
Engine IP Network Type	The type of network assigned to a query engine instance, which can be either public or private.	Yes
Use TLS	Indicates if TLS support is enabled. Teradata recommends enabling this option.	Yes
Service TLS Certification	The server certificate to authenticate the server identity.	No
Service TLS Certificate Key	The server certificate key.	No

Setting

Description

Required?

Service Base URL

[Non-Editable] The root URL of the service.

Yes

Git Provider

The provider for Git integration. Currently, Regulus supports only GitHub.

Yes

Service Log Lev

The level of logging.

Yes

Engine IP Network Type

The type of network assigned to a query engine instance, which can be either public or private.

Yes

Use TLS

Indicates if TLS support is enabled. Teradata recommends enabling this option.

Yes

Service TLS Certification

The server certificate to authenticate the server identity.

Service TLS Certificate Key

The server certificate key.

To use a self-signed certificate for Service Base URL, select GENERATE TLS. A certificate and private key are generated and displayed in the respective fields.
Select Next.

Apply the following settings under Cloud Integrations: AWS.

Setting	Description	Required?
Default Region	The AWS region you want to deploy the workload in. Teradata recommends choosing the region closest to your primary work location.	Yes
Default Subnet	The default location to launch the query engine.	Yes
Default CIDRs	The list of Classless Inter-Domain Routing (CIDR) addresses used for the query engine. Use CIDR to allocate IP addresses flexibly and efficiently in your network. If you don’t specify a CIDR, the query engine is automatically associated with the default CIDR.	No
Default Security Groups	The list of security groups for the VPC in each region. If you don’t specify a security group, the query engine is automatically associated with the default security group for the VPC.	No

Setting

Description

Required?

Default Region

The AWS region you want to deploy the workload in. Teradata recommends choosing the region closest to your primary work location.

Yes

Default Subnet

The default location to launch the query engine.

Yes

Default CIDRs

The list of Classless Inter-Domain Routing (CIDR) addresses used for the query engine. Use CIDR to allocate IP addresses flexibly and efficiently in your network. If you don’t specify a CIDR, the query engine is automatically associated with the default CIDR.

Default Security Groups

The list of security groups for the VPC in each region. If you don’t specify a security group, the query engine is automatically associated with the default security group for the VPC.

Select Next.

Apply the following settings under Configure GitHub.

Setting	Description	Required?
GitHub Application URL	[Non-Editable] The URL where the Workspaces server is hosted.	Yes
GitHub Callback URL	[Non-Editable] The URL you are redirected to after you authorize.	Yes
GitHub Client ID	The Client ID you received from GitHub on creating your OAuth App.	Yes
Use TLS	Enable TLS support.	Yes
GitHub Client Secret	The Client secret ID you received from GitHub on creating your OAuth App.	Yes
GitHub Organization	The name of the GitHub organization account that you use to collaborate with your team.	No
GitHub Base URL	The base URL of your GitHub account. The URL may vary based on your account type. For example, https://github.company.com/ for GitHub Enterprise account.	No

Setting

Description

Required?

GitHub Application URL

[Non-Editable] The URL where the Workspaces server is hosted.

Yes

GitHub Callback URL

[Non-Editable] The URL you are redirected to after you authorize.

Yes

GitHub Client ID

The Client ID you received from GitHub on creating your OAuth App.

Yes

Use TLS

Enable TLS support.

Yes

GitHub Client Secret

The Client secret ID you received from GitHub on creating your OAuth App.

Yes

GitHub Organization

The name of the GitHub organization account that you use to collaborate with your team.

GitHub Base URL

The base URL of your GitHub account. The URL may vary based on your account type. For example, https://github.company.com/ for GitHub Enterprise account.

Select Save and then select Login. You are redirected to GitHub.
Log on with your GitHub credentials to authorize Workspaces.

After authentication, you are redirected to the Workspaces Profile page, and an API Key is generated. You can use the API Key to make requests to the Workspaces service.

A new API Key is generated each time you connect to Workspaces.

Install a Regulus interface

You can use either JupyterLab or Workspaces CLI as your Regulus interface.

JupyterLab: Install using one of the following methods:
- Docker Engine
- Docker Compose
Workspaces CLI: See Use Regulus With Workspaces CLI.

Install JupyterLab using Docker Engine

Pull the Docker image from the DockerHub at https://hub.docker.com/r/teradata/regulus-jupyter.

Run the Docker image once you’ve set the JUPYTER_HOME variable.

Modify the directories based on your requirements.

docker run -detach \
  --env “accept_license=Y” \
  --publish 8888:8888 \
  --volume ${JUPYTER_HOME}: /home/jovyan/JupyterLabRoot \
  teradata/regulus-jupyter:latest

The command downloads and starts a JupyterLab container and publishes the ports needed to access it. Connect to JupyterLab using the URL: http://localhost:8888 and enter the token when prompted. For detailed instructions, see Teradata Vantage™ Modules for Jupyter Installation Guide or Use Vantage from a Jupyter Notebook.

Install JupyterLab using Docker Compose

With Docker Compose, you can easily configure, install, and upgrade your Docker-based JupyterLab installation.

Install Docker Compose. See https://docs.docker.com/compose/install/.

Create a docker-compose.yml file.

version: "3.9"

services:
  jupyter:
    deploy:
      replicas: 1
    image: teradata/regulus-jupyter:latest
    environment:
      - "accept_license=Y"
    ports:
      - 8888:8888
    volumes:
      - ${JUPYTER_HOME:-./volumes/jupyter}:/home/jovyan/JupyterLabRoot/userdata
      - ${WORKSPACES_AWS_CONFIG:-~/.aws}:/root/.aws

Go to the directory where the docker-compose.yml file is located and start JupyterLab.
```
Docker compose up -d
```
Once the JupyterLab server is initialized and started, you can connect to JupyterLab using the URL: http://localhost:8888 and enter the token when prompted. For detailed instructions, see Teradata Vantage™ Modules for Jupyter Installation Guide or Use Vantage from a Jupyter Notebook.

Congrats! You’re all set up to use Regulus.

Next steps

Get started with Regulus by running a simple workflow. See Run a Sample Workload in JupyterLab.
Interested in learning how Regulus can help you with real-life use cases? Coming soon! Keep watching this space for the GitHub link.

If you have any questions or need further assistance, please visit our community forum where you can get support and interact with other community members.

Did this page help?