Tableau Server in a Container - Using the Setup Tool

Introduction

Tableau Server in a Container is Tableau's first container-based server offering. Tableau Server in a Container is an all-in-one Tableau Server instance running inside of a Linux Docker container. In other words, a Tableau Server in a Container image is a docker image that runs an entire self-contained Tableau Server application. Tableau Server in a Container is our first of many steps to support Tableau Server running in container-based environments. The easiest way to understand the concept of Tableau Server in a Container is to think of it like a VM with Tableau Server pre-installed. The image is based on a UBI 8 image (CentOS 7.x for version 2022.1 and earlier) and runs supervisord (instead of systemd) inside the container. When the container starts supervisord, it will immediately attempt to initialize and start Tableau Server. Much of the documentation here aims to describe how to provide configuration and leverage automation so you can run Tableau Server in Docker environments.

The Tableau Server in a Container Image Setup Tool helps you create and customize container images to include custom packages and artifacts. One of the primary functions of the tool is to build the container image and install custom data connectors.

Limitations for Tableau Server in a Container

  • Tableau Server in a Container only supports license activation using Server ATR. Offline activation using Server ATR is supported in 2023.1 and later. This functionality is available in Containers but requires extra steps and approval. If you need to run Tableau Server in a Container in an air-gapped or offline environment, contact your Account representative for more information.
  • Tableau Server in a Container does not currently support the Resource Monitoring Tool (RMT) agent.
  • Kerberos is not supported in Tableau Server in a Container.

Tableau Server in a Container Setup Tool

The Tableau Server in a Container Setup Tool, build-image, builds a custom Tableau Server in a Container image from a Tableau .rpm Installer and the provided configuration files.

The Setup tool takes a Tableau Server installer and your drivers and other artifacts as input and creates a Docker image. When the build-image tool is used properly the newly generated image will have installed the desired artifacts.

Supported distributions for building

Building the Tableau Server in a Container Docker image is only supported on a RHEL-based Linux system (RHEL, CentOS, or Amazon Linux 2). Building on any other Linux distributions may be possible but is currently untested and unsupported. Building images on macOS is not supported. The image created is based on a UBI 8 image (CentOS 7.x for version 2022.1 and earlier).

You must have Docker version 18.09 or later installed on the host in order to build the container images. In general, we recommend using the latest stable version of Docker. Some Linux distros only provide older versions of Docker in their software repositories, in which case you may need to install Docker from a different source. Docker versions earlier than version 18.09 do not include features that are required for Tableau Server in a Container.

Download the necessary files

To use the Setup Tool, you need to download both the tool and a compatible Server Installer .rpm file. The Installer file must be version 2021.2.0 or later. Both files can be downloaded from the Tableau Server page(Link opens in a new window).

  1. Download the Server installer file, tableau-server-<version>.rpm version 2021.2.0 or later.

  2. Download the Server in a Container Setup tool, tableau-server-container-setup-tool-<version>.tar.gz.

Installation

The Tableau Server in a Container Setup Tool is provided as a tarball. You will need to extract the contents of the compressed file. Here is an example which assumes the Tableau Server in a Container setup tool archive is in your current directory:

tar -xzf tableau-server-container-setup-tool-<VERSION>.tar.gz

This creates a new directory, tableau-server-container-setup-tool-<VERSION> with the build-image script you use to run the tool.

Complete the registration form

Edit the registration file to provide your unique identifying information needed to register Tableau Server in accordance with the End User License Agreement. The file, reg-info.json, serves as a template for your required, uniquely identifiable registration information and is located in the top directory of the Tableau Server in a Container Setup Tool. This file is used to register the Tableau Server instance running in the image. Providing accurate information will ensure the registration process completes properly.

The eula field value is pre-filled with "accept" to indicate you are accepting our End User License Agreement (EULA). You can view the EULA in the EULA directory of the build tool. As outlined in the EULA, you must submit a uniquely identifiable user registration when activating Tableau Server. When you are done editing the registration file, the other fields should have values that reflect your unique information. This file is used to register the Tableau Server instance running in the image. Providing accurate information will ensure the registration process completes and your submission meets the requirements of the license grant.

Note: You must accept the EULA to use Tableau Server. If you do not accept the EULA, you cannot run Tableau Server.

The registration file template reg-info.json before editing:

{
"zip" : "<value>",
"country" : "<value>",
"city" : "<value>",
"last_name" : "<value>",
"industry" : "<value>",
"eula" : "accept",
"title" : "<value>",
"phone" : "<value>",
"company" : "<value>",
"state" : "<value>",
"department" : "<value>",
"first_name" : "<value>",
"email" : "<value>"
}

How to use the tool

There is an executable script in the setup tool called build-image. Running this with the -h option displays the help:

./src/build-image -h
Usage: build-image --accepteula -i [INPUT_IMAGE_NAME] -o [OUTPUT_IMAGE_NAME] [optional arguments]
Creates new Tableau Server image with pre-installed database drivers, configuration, and instructions.
REQUIRED

--accepteula              Indicate that you have accepted the End User License Agreement (EULA).

The EULA is available in the EULA directory of this tool.

-i installer              Path to the Tableau Server installer.

OPTIONAL

-o output name            Tag of target generated Tableau Server image.

-e environment file       Optional environment file to configuration overrides to docker image at build time.

-v setup tool version     Prints the Setup tool version.


-b base image version     Prints the default base image URL.

Basic example usage:

./build-image --accepteula -i tableau-server-image.rpm

Running the command without providing artifacts or a setup script will work, but doesn't really do anything because it would not be copying or installing any additional resources into the original Tableau Server in a Container image.

Orchestration

Tableau only provides documentation and support for Tableau Server containers running on Linux. Tableau does not provide documentation or support for container orchestration systems like Kubernetes or Docker Swarm. Kubernetes can, however, be used to deploy Tableau Server in a Container. For resources and guidance on deploying Tableau containers in Kubernetes, refer to our community-supported GitHub project: https://github.com/tableau/tableau-server-in-kubernetes(Link opens in a new window).

Customizing the image

Setting Environment Variables at Build Time

A subset of environment variables that can customize your image can only be set when the image is built. This includes user, group, and other properties that require root privilege inside the container. Root actions are not available by default at runtime. Additionally it can be useful to bake certain environment variables into the image at build time so they do not have to be set every time the image is run. All of these environment variables can be set by passing in an environment file to the build-image script.

Environment File

The environment file can be passed to the build-image script using the -e argument. The file must conform to this format:

<KEY>=<VALUE>
<KEY>=<VALUE>
Example Usage:

Create an environment file with the correct format:

UNPRIVILEGED_TABLEAU_UID=1012
UNPRIVILEGED_TABLEAU_GID=1020
TABLEAU_USERNAME=myuser
TABLEAU_PASSWORD=pw

Pass the file to the image builder

./build-image --accepteula -i tableau-server-2020-3.x86_64.rpm -e <path-to-env-file>
Environment Variables

Any environment variable can be set in the environment file. Take a look at the Environment Variables section to see the complete list.

Build time environment variables can only be set when this script is run to build the image:

Environment name Default Description
BASE_IMAGE_URL Use the build tool command: build-image -b The default image specified in the build-image tool and Dockerfile is the only officially supported base image. This parameter can be used to either pull a copy of this specific base image from a custom docker image repository or define a custom base image. If you choose to use a custom-defined base image (see Defining a Custom Base Image for more details), it is your responsibility to ensure it is based on UBI 8 (CentOS 7 or RHEL 7 for version 2022.1 and earlier) and contains the necessary resources to run Tableau Server properly.
PRIVILEGED_TABLEAU_GID 997 The GID of the privileged tableau group.
UNPRIVILEGED_TABLEAU_GID 998 The GID of the unprivileged tableau group.
UNPRIVILEGED_TABLEAU_UID 999 The UID of the user that runs tableau processes (single user deployment).
UNPRIVILEGED_USERNAME tableau The string name of the unprivileged user.
UNPRIVILEGED_GROUP_NAME tableau The string name of the unprivileged group.
PRIVILEGED_GROUP_NAME tsmadmin The string name of the privileged group.
LANG en_US.UTF-8 Locale setting

Drivers, Certificates, and other files

The Tableau Server image does not come with pre-installed data connectors or drivers. You will need to create a bash setup-script that will instruct the build-image script to install the data connectors Tableau Server will need. These are the steps you would take:

  1. Make sure the Tableau Server in a Container setup tool is installed properly

  2. Download the driver from the Tableau driver page: https://www.tableau.com/en-us/support/drivers(Link opens in a new window)

  3. Copy the downloaded driver file into the customer-files directory in the Tableau Server in a Container setup tool.

    The customer-files directory will be copied into the docker image. It will be located in the following path inside the container: /docker/customer-files

  4. Edit the file in the Tableau Server in a Container setup tool customer-files/setup-script to tell Docker how to install the driver.

    The script is just an executable bash file that is executed when the Docker image is built. (Technically it can be used to perform any arbitrary actions in the image including environment setup, configuration, etc.)

    The script will be run inside the container so be mindful that the commands must work when executed inside the Tableau Server in a Container image.

    For example, if you want to install a driver named mydriver.rpm you would write this in setup-script:

    yum install -y /docker/customer-files/mydriver.rpm
Tableau Administrative Views

Tableau Administrative views require the PostgreSQL driver to be installed. If you plan on using these views you will need to follow the steps above and install the PostgreSQL driver. For more information about Administrative views, see Administrative Views

Defining a Custom Base Image

The default base image used to build the Tableau Server container is a UBI 8 image (CentOS 7.x for version 2022.1 and earlier) sourced from Docker Hub. In some cases you may want to configure the build-image tool to pull the image from a different docker image repository. For example, your company may manage an internal docker repository and not want the build-image pulling from a public repository. Use the following steps to customizing the base image path:

  1. Use the following command to view the current build-image tool's default base image name and version:

    ./build-image -b
  2. Pull the exactly matching base image name and version from Docker Hub and store/cache it in your preferred image repository (per your company's image policies)

  3. Come back to the build-image tool. Create or modify an existing environment file to include the BASE_IMAGE_URL environment key with the value set to a new docker image registry path:

    BASE_IMAGE_URL=<custom-image-registry-path>
  4. Build the image with the environment file:

    ./build-image --accepteula -i <rpm> -e <path-to-env-file>

These steps enable you to specify a completely different base image. This capability is supported only for UBI 8-based images (RHEL and CentOS 7.x for version 2022.1 and earlier) and is provided to help customers create more secure images.

Using a base image other than the default specified by Tableau carries the risk of producing an image that does not start or function properly. If you choose to use a custom base image, you are responsible for ensuring that the base image enables Tableau Server to run properly. We recommend using the default base image unless it is unacceptable to your organization for some reason, such as security concerns.

The custom base image must be based on UBI 8 (RHEL 7 or CentOS 7 for version 2022.1 and earlier). Using any other distro will result in an unsupported image.

Using internal repositories for yum and pip

The Tableau Server in Container image is configured to use the default yum and pip repositories to pull dependent packages. If you need to edit, remove, or add repositories (for example, internal repositories might be used to improve security), you will need to modify one of the Image Setup Tool's initialization scripts.

Modify the <setup_tool>/src/image/init/setup_default_environment.bash script in the source code to use the internal repositories. Please keep any repository files required for the internal repository in the <setup_tool>/src/image/init/ directory. That directory will be copied to the docker image.

Base Images and Security

Many customers will run container scanning tools (such as AquaScan or TwistLock) against the generated Tableau Server Docker image. These security tools will generate a report of potential security vulnerabilities (or Common Vulnerabilities and Exposures or CVE). There are two types of vulnerabilities associated with the Tableau Server in a Container image:

  • CVEs associated with Tableau Server or with a library we have a dependency on.
  • CVEs associated with the underlying Linux distro.

Tableau is responsible for CVEs associated directly with Tableau Server. The Security Team analyzes these reports to determine impact and severity to help prioritize the issues for resolution. The baseline remediation priority and timelines will be determined by the original CVSS severity scoring. Third party component security updates will not usually be back-ported into older releases unless there is an executable code path that exposes the vulnerability.

With the containerized distribution model, customers are faced with a different set of challenges around OS Layer vulnerabilities. Traditionally, with Tableau Server, Tableau would focus its efforts on delivering a secure application and the customer is responsible for managing the Operating Systems (Linux or Windows). However, with containerization, the OS (UBI 8 starting in version 2023.3, CentOS 7.x or RHEL 7.x for version 2022.1 and earlier) and the application are packaged together in one container. Tableau takes responsibility for the CVE associated with Tableau Server and for determining if a CVE from a third party library would impact customers. However customers must be responsible for the OS layer issues. In order for customers to address the security issues in the OS layer customers may replace the base OS layer with their own version (UBI 8-based for version 2022.3 and later, RHEL or CentOS 7.x for version 2022.1 and earlier). In doing this you must validate that Tableau Server runs correctly. Removing a library Tableau Server is dependent on because of security issues may result in a non-functioning instance of Tableau Server. If you change the base OS layer customers are responsible for validating that it works.

Hardening Tableau Server in a Container

You can apply the standard hardening steps to Tableau Server in a Container. For more information on hardening Tableau Server, see Security Hardening Checklist.

Deployment Configuration Examples

Docker

Tableau Server in a Container Basic Usage
docker run \
-e LICENSE_KEY=<key>
-p 8080:8080
-d <Tableau Server in a Container image ID or tag>
Tableau Server in a Container Basic Usage with Automated Initial Admin User
docker run \
-e LICENSE_KEY=<key> \
-e TABLEAU_USERNAME=<myadmin> \
-e TABLEAU_PASSWORD_FILE=/etc/tableau-admin-secret \
-v <full-path-to-pw-file>:/etc/tableau-admin-secret \
-p 8080:8080 -d <Tableau Server in a Container image ID or tag>
TSM only mode
docker run \
-e TSM_ONLY=1 \
-p 8080:8080 -d <Tableau Server in a Container image ID or tag>
Multi-Node Basic Usage
Initial Node

Option 1: Use this if the server configuration (CONFIG_FILE) specifies a multi-node topology:

docker run \
-v <network-shared-directory>:/docker/config/bootstrap \
-v <full-path-to-config-file>:/docker/config/config.json:ro \
-e LICENSE_KEY=<key> \
-p 8080:8080 -p 8800-9000:8800-9000 -p 27000-27010:27000-27010 \
--hostname=<name-of-host-machine> \
-d <Tableau Server in a Container image ID or tag>

Option 2: Use this if you want a multi-node deployment even if server configuration does not specify multi-node topology:

docker run \
-v <network-shared-directory>:/docker/config/bootstrap \
-e LICENSE_KEY=<key> -e ALWAYS_WRITE_BOOTSTRAP_FILE=1 \
-p 8080:8080 -p 8800-9000:8800-9000 -p 27000-27010:27000-27010 \
--hostname=<name-of-host-machine> \
-d <Tableau Server in a Container image ID or tag>
Additional node
docker run \
-v <network-shared-directory>:/docker/config/bootstrap \
-e BOOTSTRAP_INSTALL=1 \
-p 8080:8080 -p 8800-9000:8800-9000 \
--hostname=<name-of-host-machine> \
-d <Tableau Server in a Container image ID or tag>
Externalize Data Usage
docker run \
-v <empty-data-dir>:/var/opt/tableau \
-e LICENSE_KEY=<key> \
--hostname=localhost \
-p 8080:8080 -d <Tableau Server in a Container image ID or tag>
Init-Container Basic Usage

Init Container

docker run \
-v <empty-data-dir>:/var/opt/tableau \
-e LICENSE_KEY=<key> \
-e INIT_CONTAINER=1 \
--hostname=localhost \
-p 8080:8080 -d <Tableau Server in a Container image ID or tag>

Run Container

docker run \
-v <empty-data-dir>:/var/opt/tableau \
--hostname=localhost \
-p 8080:8080 -d <Tableau Server in a Container image ID or tag>
Basic Restore from Backup Single-Node
docker run \
-v <full-path-to-backup-file>:/docker/config/backup/backup-file.tsbak \
-v <full-path-to-config-only-file>:/docker/config/config.json:ro \
-e LICENSE_KEY=<key> \
-p 8080:8080 -d <Tableau Server in a Container image ID or tag>

Docker-Compose

version: '3.2'
services:
    tableau-server:
         hostname: localhost
         volumes:
              - <your-tsm-command-file>:/docker/config/tsm-commands:ro
              - <your-config-file >:/docker/config/config.json:ro
         ports:
              - "8080:8080"
         image: ${IMAGE_NAME}
         environment:
              - LICENSE_KEY=<license-key>

 

 

Thanks for your feedback!Your feedback has been successfully submitted. Thank you!