Deploy and Setup Teradata AI Unlimited Workspace Service Using Docker

This product is in preview and is subject to change. If you’re interested in learning more about this offering, contact Teradata Support.

Overview

This document outlines the steps for deploying and setting up Teradata AI Unlimited workspace service using Docker.

You can install the workspace service using:

Docker Engine
Docker Compose

To use Teradata AI Unlimited with the workspace client, see Use Teradata AI Unlimited With Workspace Client.

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/.
CSP account: You can host the engine on AWS or Azure.
- AWS
- Azure
Sign up for an AWS Free Tier account at https://aws.amazon.com/free/. To set up AWS CLI, see https://docs.aws.amazon.com/cli/latest/userguide/getting-started-quickstart.html.

Sign up for an Azure free account at https://azure.microsoft.com/en-us/free. Install Azure CLI and configure the credentials on the machine running workspace service. See https://learn.microsoft.com/en-us/cli/azure/get-started-with-azure-cli.
Docker: To download and install Docker, see https://docs.docker.com/docker-for-windows/install/.

Load Docker image and prepare environment

The Docker image is a monolithic image of the workspace service running the necessary services in a single container.

Pull the docker image from Docker Hub.

docker pull teradata/ai-unlimited-workspaces

Before proceeding, make sure to:

Copy and retain the CSP environment variables from your AWS Console.
- AWS: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN
  
  See Environment Variables.
- Azure: ARM_SUBSCRIPTION_ID, ARM_CLIENT_ID, and ARM_CLIENT_SECRET
  
  For information on obtaining environment variables using Azure CLI, see Azure Authentication.
Set the environment variable, WORKSPACES_HOME, to the directory where the configuration and data files are located. Make sure that the directory exists, and that appropriate permission is granted. If you don’t set WORKSPACES_HOME, the default location is ./volumes/workspaces.

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

Deploy workspace service 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/ai-unlimited-workspaces:latest

For Azure, Teradata recommends deploying workspace service using Docker Compose.

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

Deploy workspace service using Docker Compose

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

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

Create a workspaces.yml file.

The following example uses a local volume to store your CSP credentials. You can create a separate YAML file containing CSP environment variables and run the Docker Compose file. For other options, see AI Unlimited GitHub: Install AI Unlimited Using Docker Compose.

AWS
Azure

version: "3.9"

services:
  workspaces:
    deploy:
      replicas: 1
    platform: linux/amd64
    container_name: workspaces
    image: ${WORKSPACES_IMAGE_NAME:-teradata/ai-unlimited-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}
    volumes:
    - ${WORKSPACES_HOME:-./volumes/workspaces}:/etc/td
    - ${WORKSPACES_AWS_CONFIG:-~/.aws}:/root/.aws

    networks:
      - td-ai-unlimited

version: "3.9"

services:
  workspaces:
    deploy:
      replicas: 1
    platform: linux/amd64
    container_name: workspaces
    image: ${WORKSPACES_IMAGE_NAME:-teradata/ai-unlimited-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}
    volumes:
      - ${WORKSPACES_HOME:-./volumes/workspaces}:/etc/td
      - ${WS_HOME:-~/.azure}:/root/.azure

    networks:
      - td-ai-unlimited

Go to the directory where the workspaces.yml file is located and start the workspace service.
```
docker compose -f workspaces.yaml
```
Once the workspace service server is initialized and started, you can access it using the URL: http://<ip_or_hostname>:3000/.

Configure and set up workspace service

Workspace service uses the GitHub OAuth App to authorize users and manage the project state. To authorize the workspace service 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 and you can view them on the Workspace service Profile page.

First-time users must complete the following steps before proceeding. If you are unsure about your VPC configuration or permissions, contact your organization administrator.

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

While registering the OAuth App, type the following workspace service 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 the workspace service, do the following:

Access workspace service 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, Teradata AI Unlimited supports GitHub and GitLab.	Yes
Service Log Lev	The level of logging.	Yes
Engine IP Network Type	The type of network assigned to an engine instance, which can be either public or private. Select the Private option if you’re deploying the engine in the same VPC as the workspace service.	Yes
Use TLS	Indicates if TLS support is enabled. If your instance is only accessible from within a private network and to trusted users, you can ignore the default value. Teradata recommends enabling the TLS option for sensitive data, public networks, and compliance requirements.	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, Teradata AI Unlimited supports GitHub and GitLab.

Yes

Service Log Lev

The level of logging.

Yes

Engine IP Network Type

The type of network assigned to an engine instance, which can be either public or private. Select the Private option if you’re deploying the engine in the same VPC as the workspace service.

Yes

Use TLS

Indicates if TLS support is enabled. If your instance is only accessible from within a private network and to trusted users, you can ignore the default value. Teradata recommends enabling the TLS option for sensitive data, public networks, and compliance requirements.

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 Save Changes.

Apply the following settings under your choice of Cloud Integrations: CSP.

Setting	Description	Required?
Default Region	The region where you want to deploy the engine. Teradata recommends choosing the region closest to your primary work location.	Yes
Default Subnet	The subnet that provides the engine instance with a route to an internet gateway. If you don’t specify a subnet, the engine is automatically associated with the default subnet.	Yes
Default IAM Role	The default IAM identity that determines what a user can and cannot do in AWS. When a default IAM role is assigned to a user or resource, the user or resource automatically assumes the role and gains the permissions granted to the role.	No
Resource Tag	The key-value pair applied to a resource to hold metadata about that resource. With a resource tag, you can quickly identify, organize, and manage the resources you use in your environment.	No
Default CIDRs	The list of Classless Inter-Domain Routing (CIDR) addresses used for the engine. Use CIDR to allocate IP addresses flexibly and efficiently in your network. If you don’t specify a CIDR, the 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 engine is automatically associated with the default security group for the VPC.	No
Role Prefix	The string of characters prepended to the name of a role. You can use a role prefix to organize and manage roles and to enforce naming conventions.	No
Permission Boundary	The maximum permissions an IAM entity can have regardless of the permissions defined in the identity-based policy. You can define and manage the user permissions and roles and enforce compliance requirements.	No

Setting

Description

Required?

Default Region

The region where you want to deploy the engine. Teradata recommends choosing the region closest to your primary work location.

Yes

Default Subnet

The subnet that provides the engine instance with a route to an internet gateway. If you don’t specify a subnet, the engine is automatically associated with the default subnet.

Yes

Default IAM Role

The default IAM identity that determines what a user can and cannot do in AWS. When a default IAM role is assigned to a user or resource, the user or resource automatically assumes the role and gains the permissions granted to the role.

Resource Tag

The key-value pair applied to a resource to hold metadata about that resource. With a resource tag, you can quickly identify, organize, and manage the resources you use in your environment.

Default CIDRs

The list of Classless Inter-Domain Routing (CIDR) addresses used for the engine. Use CIDR to allocate IP addresses flexibly and efficiently in your network. If you don’t specify a CIDR, the 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 engine is automatically associated with the default security group for the VPC.

Role Prefix

The string of characters prepended to the name of a role. You can use a role prefix to organize and manage roles and to enforce naming conventions.

Permission Boundary

The maximum permissions an IAM entity can have regardless of the permissions defined in the identity-based policy. You can define and manage the user permissions and roles and enforce compliance requirements.

Select Save Changes.

Apply the following settings under Git Integrations.

Setting	Description	Required?
GitHub Client ID	The Client ID you received from GitHub on creating your OAuth App.	Yes
GitHub Client Secret	The Client secret ID you received from GitHub on creating your OAuth App.	Yes
Auth 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 Client ID

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

Yes

GitHub Client Secret

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

Yes

Auth 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 Authenticate. You are redirected to GitHub.
Log on with your GitHub credentials to authorize workspace service.

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

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

Teradata AI Unlimited workspace service is ready!

Next steps

Connect workspace service to a Teradata AI Unlimited Interface and deploy an engine. See Deploy a Teradata AI Unlimited Interface Using Docker.
Interested in learning how Teradata AI Unlimited 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?