Tableau Server on Linux Help

Limitations for Tableau Server in a Container

• Tableau Server in a Container only supports licence 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 Image

The Tableau Server in a Container Image is a Docker image that contains all of Tableau Server. The image is built using the Tableau Server in a Container Setup Tool. When built, the image includes Tableau Server, but it is not yet initialised. The default user in a Tableau Server in a Container image is a non-root unprivileged user.

Prerequisites

Run the configure-container-host script

When Tableau Server is installed without a container, certain resource limits and coredump properties are changed as part of the installation process. This is done to help optimise the performance of Tableau Server. A Tableau Server in a Container image does not have the ability to make these changes on the host machine, so we recommend running the configure-container-host script that is provided in the Tableau Server in a Container Setup Tool on any machine that will be running Tableau Server in a Container images. This will help ensure the performance of the Tableau Server in a Container image is equivalent to that of its non-container counterpart.

To run the configure-container-host script:

1. Locate the script (configure-container-host) in the top-level directory of the Tableau Server in a Container Setup Tool.

2. Copy it to the environments in which you plan on running Tableau Server.

3. Determine the unprivileged user account/UID that will run as the default user of the Tableau Server in a Container image. This user should exist on the host machine and should match the UID set in the Tableau Server container UNPRIVILEGED_TABLEAU_UID environment variable. If you did not set this when creating your Docker image, the default unprivileged user ID inside the container is 999. If you are using Docker user-mapping, this UID should correspond with the user that exists on the host machine.

4. Execute the script as root:

   sudo ./configure-container-host -u <uid>

Running the Image

To run a Tableau Server in a Container docker image, the simplest command to get a Tableau Server in a Container Image running is the following:

docker run \
-e LICENSE_KEY=<key>
-p 8080:8080
-d <Tableau Server in a Container image ID or tag>

This will run docker in the background and, after some time, will result in a fully installed instance of Tableau Server. Tableau Server can take 10 to 20 minutes to fully start up, depending on the hardware of the computer running the image. You can confirm that the container is running by typing the command docker ps. Once Tableau Server is operational, the initial Tableau Server administrator account will need to be created. This step can be automated. For more information, see Automate Initial Tableau Server Administrator.

Basic Run Arguments Summary

All the options used in the Docker run command are necessary. Often, more options will be provided to leverage different functionality in the image. For now, let's take a closer look at just the arguments used in the simplest Docker run command for Tableau Server in a Container:

Automate Initial Tableau Server Administrator

When Tableau Server starts up for the first time an initial administrator user must be created before remote network connections to Tableau Server are permitted. This can be done by running the tabcmd initialuser -s localhost:8080 -u <username> -p <password> command inside the container. You may also set admin credentials via environment variables. TABLEAU_USERNAME and TABLEAU_PASSWORD or TABLEAU_PASSWORD_FILE (preferred) are the environment variables that can be set to pass in initial admin credentials. For more information on password management, see Password Management.

For more information on the tabcmd initialuser command, see initialuser.

Example

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>

Licensing

Licensing in Containers

Licensing of Tableau Server in a Container uses the Server Authorisation-To-Run (ATR) service to activate Tableau Server deployed in the cloud, containers or virtual environments without running out of licence activations. The ATR service achieves this by providing short-term leases of configurable duration (ATR duration) until the product key expiry date is met. ATR abstracts Tableau licensing from underlying hardware changes, which is a fundamental aspect of container deployments. Since Server ATR requires the container to be able to reach the ATR service hosted by Tableau, the containers require internet access. Tableau Server in a Container does not support offline or manual activation. See Activate Tableau Server Using the Authorisation-To-Run (ATR) Service for more details.

Important: You must provide either the LICENSE_KEY or LICENSE_KEY_FILE environment variables (only set one).

When upgrading Tableau Server in a container, if you’ve used the maximum number of activations for your licence, Tableau Server cannot start until the ATR duration has elapsed (4 hours/14400 seconds by default). For more information about setting or changing the ATR duration, see Activate Tableau Server Using the Authorisation-To-Run (ATR) Service(Link opens in a new window).

Licence Environment Variable

Tableau Server in a Container supports setting licence keys using an environment variable: the LICENSE_KEY can contain one or more keys (-e LICENSE_KEY="<key1> , <key2>") via a comma-separated list.

Example

docker run \
-e LICENSE_KEY="<key1>, <key2>" \
-p 8080:8080 -d <Tableau Server in a Container image ID or tag>

Licence File

Tableau Server in a Container also supports setting licence keys using a file. Mount a file to the default licence key file location in the container (/docker/config/license_file) or as otherwise specified by the environment variable LICENSE_KEY_FILE.

Example

docker run \
-v <full-path-to-license-file>:/docker/config/license_file \
-p 8080:8080 -d <Tableau Server in a Container image ID or tag>

Requested licence lease time

You can specify the ATR licence lease time in a Tableau Server container by setting the environment variable REQUESTED_LEASE_TIME. You must provide the lease time in seconds, with the minimum duration being 3600 seconds (or 1 hour). It is recommended that you lower the lease time when experimenting and testing Tableau Server to reduce the likelihood of reaching the max activated lease limit. For production deployments, it is strongly recommend not to set the REQUESTED_LEASE_TIME parameter (thus using the default value), so Tableau can determine the ideal lease time.

Example

docker run \
...
-e REQUESTED_LEASE_TIME=<time-in-seconds> \
-p 8080:8080 -d <Tableau Server in a Container image ID or tag>

Running an Uninitialised Image

Tableau Server has two phases of installation, first the Tableau Service Manager (TSM) services are installed. In a typical On-Premise installation, this step is a time for server admins to register their server, activate their licences and configure the server to behave the way they want it to. The second phase of installation is setting up and starting the Tableau Server processes which will handle end-user traffic and related business logic.

The default behaviour of Tableau Server in a Container images is to automate all installation steps so the docker run command eventually results in a fully functional server. However, if you want to start a Tableau Server in a Container image and have it only running the TSM services (what a server administrator would expect if they just ran initialize-tsm), you can do this by passing the TSM_ONLY flag as an environment variable.

For example:

docker run \
-e TSM_ONLY=1 \
-p 8080:8080 -d <Tableau Server in a Container image ID or tag>

Interacting with the Image

When you have a Tableau Server in a Container image running, you can call TSM and tabcmd commands directly. Those tools are added directly to the environment path of the pid 1 user (which is root at this time). This means you can call TSM and tabcmd commands as follows:

docker exec -it <container> tsm status -v

docker exec -it <container> tabcmd initialuser -s localhost -u <admin> -p <secret>

It is also possible to open a shell in the container to perform more general operations. This is generally not recommended except for debugging purposes:

docker exec -it <container> bash

TSM Web UI and Remote CLI

The TSM Web UI and remote CLI is not accessible by default. This is because it requires a username and password to authenticate and by default the user running tableau server processes in the container is not provided a password. This is done for security reasons (we do not recommend shipping images with a default password inside them as that would allow remote access). In some cases the TSM Web UI and making remote access calls using the TSM CLI can be useful. If you want to use these features you will need to follow the steps outlined below to create a remote access user account.

For more detailed information about the TSM Web UI and CLI see Sign in to Tableau Services Manager Web UI.

Create a TSM Remote User

Specify the TSM_REMOTE_UID and TSM_REMOTE_USERNAME environment variables when you build the Tableau Server in a Container image using the Setup Tool. Creation of a TSM-enabled account in the image requires privileged access in the image that isn't available at runtime, and therefore it can only be done when the Docker image is being built by the Tableau Server in a Container Setup Tool (build-image).

Example Tableau Server in a Container Setup Tool environment file:

TSM_REMOTE_UID=1010
TSM_REMOTE_USERNAME=myuser

Set the password for the TSM Remote User

The Tableau Server in a Container image requires a password for the account when the image is run. There are two ways you can set the password for this account.

Secrets File (Recommended)

Create a file named remote-user-secret, write the password into the file and mount it into the container at runtime. TSM_REMOTE_PASSWORD_FILE determines the expected location (default location is /docker/config/remote-user-secret) of the secrets file in the container.

Example remote-user-secret file:

mypassword

Example docker run command:

docker run \
-e LICENSE_KEY=<key>
-v {absolute-path}/remote-user-secret:/docker/config/remote-user-secret
-p 8080:8080 \
-p 8850:8850 \
-d <Tableau Server in a Container image ID or tag>

Environment Variable

You can also simply set the TSM_REMOTE_PASSWORD environment variable when starting the docker image.

Example docker run command:

docker run \
-e LICENSE_KEY=<key>
-e TSM_REMOTE_PASSWORD=<password>
-p 8080:8080 \
-p 8850:8850 \
-d <Tableau Server in a Container image ID or tag>

Security Notes

• Port 8850 must be exposed to receive TSM request traffic.
• If the password is not set properly in the image at runtime, the container will exit immediately.
• TSM relies on the image's Linux user account system. In this case the account is restricted inside the image. This means the account will have a restricted shell and is limited to executing two commands: /bin/true and passwd.

How to Rotate the TSM Remote User's Password

If you want to rotate the account password of the TSM remote user, you can do this using either of these options:

Start a new Tableau Server in a Container

The account's password is set every time the container starts up. If you are persisting Tableau data outside the container, then starting a fresh image with a new password will effectively rotate the password.

1. Shut down and remove the running image
2. Set a new password value in either TSM_REMOTE_PASSWORD or TSM_REMOTE_PASSWORD_FILE environment variables (see above) in your image configuration.
3. Start the image up again.

Rotate the password manually inside a running container

If you don't want to shut down the image, you can still rotate the password manually.

1. Open a shell in the running container
2. Log in as the remote user account using the su command

3. Run the passwd command to change the password.

   Warning: These manual rotations only persist as long as the container instance's write layer remains. If you delete the container, the manual changes will not be applied when a new container is started.

Initial Configuration Options

Configuring Tableau Server in a Container is essential for getting the Tableau Server behaviour you want. Tableau Server in a Container is a clean installation of Tableau Server, so you need to provide the same information to the container as when configuring Tableau Server outside a container.

Runtime Environment Variables

The runtime environment variables below tell the Tableau Server in a Container image how to deploy Tableau Server. A subset of these will be described in greater detail.

All of these values are designed to be overridden to enable more flexibility for configuration.

Readonly Environment Variables

These are environment properties that describe some of the basic properties of the Tableau Server in a Container image. Overriding these values is not recommended.

Build-Time Environment Variables

Tableau Server Configuration Overrides

These environment variables can be overwritten by Docker to point at any file in the container. So if you want to specify a different mount point, you are welcome to do so.

Tableau Server needs a configuration file to start and run:

CONFIG_FILE=/docker/config/config.json

CONFIG_FILE refers to a TSM configuration file. The format and usage is identical to the configuration file described in Configuration File Example.

Pre-initialisation and Post-initialisation Commands

Tableau Server runs an automated installation script designed to take Server from a pre-initialised state to fully running. However, sometimes you may want to add in your own automation code in the initialisation process. We offer two hooks to do this, the pre-initialisation script and post-initialisation script.

Pre-initialisation script

This script will run immediately after the base TSM processes are initialised and before any other TSM setup steps are executed. This is useful for executing TSM configuration commands before Tableau Server runs. For configuration changes made at this point, you do not need to apply the changes because the normal Tableau Server automation does this after your script completes.

Post-initialisation script

This script will run after all other Tableau Server initialisation and startup automation completes. Tableau Server will be fully functional and running when this script executes. Configuration changes made at this point must be applied.

Instructions

To add a custom script to one of these hooks in your image, follow these steps:

1. Write your custom script
2. Copy the custom script into the customer-files directory of the Tableau Server in Containers Build Image Tool.
3. Rename the script to be either pre_init_command or post_init_command depending on when you would like the script to run (you can use both hooks independently of each other).
4. Ensure the permissions of the script are either executable by other (chmod +rx <command-file>) or the ownership permissions match the unprivileged user in the container.

User Configuration

Tableau Server uses an unprivileged user to run server processes. This user was created inside the container when Tableau Server in a Container was initialising. By default the user is named tableau with a UID of 999. If you are deploying a Tableau Server in a Container that uses mounts to externally store data on the host machine you may prefer to change the UID to map to a UID on the host machine. Using docker username spaces is another way to achieve the same result.

Tableau Server in a Container Utilities and Tools

All Tableau Server in a Container utility and tool functions are placed under this directory:

/docker/

File Permission Management

When passing any configuration files to the container, you will want to ensure the user running the Tableau Server process inside the container has permission to access the files. To avoid granting all users access to files being mounted to the container, you can change the UID and/or the GID of the user running Tableau Server inside the container to match the user/group owner on the host. The container user will have a UID determined by the UNPRIVILEGED_TABLEAU_UID environment variable (default: 999) and GID determined by UNPRIVILEGED_TABLEAU_GID (default: 998). These values can be changed by overriding the environment variable or you can use a Docker user namespace mapping to associate the UID/GID in the container to a different UID/GID on the host.

Password Management

Certain features and options require user credentials to be provided as a configuration setting into the container. Tableau Initial Admin credentials is an example of optional credentials that enable additional features. In these cases we always provide two methods of setting the password. First, you can provide a file containing the password and supply a file path to an environment variable. Alternatively, you can set an environment variable to store the password directly.

The recommended and more secure option is to provide the password as a file path to the container. Providing a secret in a file is a well supported pattern in Docker, Docker Swarm, Kubernetes and other container orchestration systems. Storing passwords directly in environment variables is a common pattern so we do support it, but it typically means the password is less secure.

Examples

Let's take a look at the TABLEAU_USERNAME credential. You can provide the password for the user as either TABLEAU_PASSWORD or TABLEAU_PASSWORD_FILE. When running a Tableau Server in a Container image you can provide either environment variable to supply the password.

The password file environment variable expects a file path inside the container to a valid secrets file. The secrets file should be a single line containing the secret.

Example of using a secrets file

docker run \
...
-e TABLEAU_USERNAME=admin \
-e TABLEAU_PASSWORD_FILE=/etc/admin-secret \
-v <full-path-to-pw-file>:/etc/admin-secret \
-d <Tableau Server in a Container image ID or tag>

Example contents of a secrets file

mypassword23879172

Alternatively, one can directly store the password in plain text in the password environment variable. This approach is considered less secure but it is more convenient and a common pattern with containers.

Example

docker run \
...
-e TABLEAU_USERNAME=admin \
-e TABLEAU_PASSWORD=password \
-d <Tableau Server in a Container image ID or tag>

Configuring Tableau Server after it is running

Once Tableau Server has been initialised and is running, the best way to interact with the server is to use the TSM CLI tool. This is the classic Tableau Server tool for performing administrative tasks. In the future we will support Tableau Server reacting to changes in the static configuration provided in the CONFIG_FILE environment variable in between runs. But for now, after Tableau Server is initialised, you must interact with the server using the classic tools.

For more information on the TSM command-line see tsm Command Line Reference.

Status

There are two basic status checks for Tableau Server provided in the image. These can be used to check the aliveness and readiness of the server.

Liveness Check

The liveness check indicates whether or not TSM services are running. This means it will indicate whether the orchestrated services of Tableau Server are operating and are functioning. This check is callable here:

/docker/alive-check

Another option is to expose port 8850 which the Tableau Controller service runs to provide administrative functions through a web browser. One could periodically check the health of the service by checking the health of the service through tcp health checks.

Readiness Check

The readiness check indicates whether Tableau Server is running and business services are ready to receive traffic. This can be determined using the following script:

/docker/server-ready-check

Another option is to use tcp health checks against port 8080 (or whatever port Tableau Server is bound to receive traffic). Sometimes this kind of tcp health check is more reliable than the server-ready-check, as the server-ready-check is based on service status reported to TSM, which can sometimes be delayed as the service state is updated.

Persisting Data

Often with containers, we want the capability to shut a container down and then turn it back on without losing any important information. Tableau Server in a Container images support this in that you can mount certain directories outside of the container so you can completely destroy or remove container instances and still preserve your data. This data can be used to start another container instance and resume where the previous container left off.

The following sections cover the different kinds of managed state.

Tableau Server Data

Server Data is all stored in the data directory. The data directory is where all user-related data and service runtime metadata is stored. Externalising this data means your user's data can be persisted even after the Tableau Server in a Container is completely removed.

This data is transferable and can be usable with a cloud-managed block storage system, like AWS EBS volumes.

When Tableau Server in a Container is used in conjunction with External Filestore, the data directory must be on EBS. Do not use a network file system (for example, NFS) for the data directory. The External Filestore directory can be on an NFS volume.

Static Hostnames

Tableau Server does not handle dynamic hostname changes well, so it is important to specify the container's internal hostname so it is consistent between container runs. The hostname inside a container is arbitrary and can be set to any value. Using the --hostname option allows one to specify the internal hostname of the container. Make sure subsequent containers using the same persistent data are run using the same hostname value.

This is not to be confused with multi-node server installations. In these, additional nodes should each be assigned a different hostname. What matters is when any single container is restarted, the replacing container that will use the same persistent data for that instance must have a matching hostname.

Complete Example

Here is an example where the data directory is mounted outside the container.

docker run \
-v <empty-data-dir>:/var/opt/tableau \
-e LICENSE_KEY=<key> \
--hostname=<static (internal) name of host machine> \
-p 8080:8080 -d <Tableau Server in a Container image ID or tag>

Backup and Restore

Tableau Server in a Container supports Tableau Server creating backups and restoring from a backup file (.tsbak). The first step is to get a Tableau Server in a Container image running, have the backup file (.tsbak) mounted in the image and set the environment variable BACKUP_FILE with the file path to the backup file. Additionally you must provide the backup json configuration file in the CONFIG_FILE environment variable. The Tableau Server container automates the restore process even for multi-node deployments. If at any point this automation fails to fully restore the system, you can always fall back on the classic Tableau Server tools and processes such as TSM commands to interact with Tableau Server in the same way you would with a non-container deployment.

For more information on how to perform a backup and restore of a standard Tableau Server instance see Perform a Full Backup and Restore of Tableau Server.

Backup in Tableau Server Container

1. Open shell inside the Tableau Server in a Container version A. Create repository backup, and topology and configuration backup files.

   docker exec -it my-server bash
   
   # Just providing filename automatically produces the backup file at /var/opt/tableau/tableau_server/data/tabsvc/files/backups/
   tsm maintenance backup -f <repository-backup>.tsbak -d
   
   # Any filepath where current user(UNPRIVILEGED USER) can write.
   tsm settings export -f /var/opt/tableau/tableau_server/data/tabsvc/files/backups/<topology-conf-backup>.json

2. Copy the files created in previous step into the host machine. Change the file permission to have read-all permission set for both files.

   docker cp my-server:/var/opt/tableau/tableau_server/data/tabsvc/files/backups/<repository-backup>.tsbak ./<repository-backup>.tsbak
   docker cp my-server:/var/opt/tableau/tableau_server/data/tabsvc/files/backups/<topology-conf-backup>.json ./<topology-conf-backup>.json
   chmod a+r ./<repository-backup>.tsbak ./<topology-conf-backup>.json

3. Store backup artefacts in a secure location. Follow the restore steps below when needed.

Restore inside Tableau Server Container

Backups from any supported Tableau Server version (container and non-container) can be restored inside the Tableau Server container.

Prerequisites

• Tableau Server backup file.
• Configuration json file containing both configuration and topology information.
• Note: You will likely need to change the backup files to have read-all permission set. Backup files are typically locked to the user that created the file, and this one will likely be different from the Tableau user running in the container.

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>

Notes:

• If you are restoring a multi-node system, you must also start the other nodes in order for the restore automation to work. See the Multi-node Tableau Server in a Container section of this document for more information. Only the initial node requires the backup file, backup configuration file and licence.
• The backup files only need to be provided in the first run of the container. Once the server is initialised, you do not need to keep mounting in the backup files.

Migrating from Tableau Server to Tableau Server in a Container

In order to migrate from a standard Tableau Server installation to Tableau Server in a Container, you must use the backup and restore technique. Backups from any supported Tableau Server version (container and non-container) can be restored inside the Tableau Server container. See the Restore inside Tableau Server Container section above for more information.

Upgrading Tableau Server Versions

There are two ways to upgrade Tableau Server. The Upgrade-Image method listed in this section is the recommended solution. However, as a fallback it is also possible to upgrade Tableau Server using Backup/Restore.

Upgrading through Upgrade-Image method

The Upgrade Image is a Docker image that can be built using the build-upgrade-image script from the Tableau Server in a Container setup tool. The purpose of the image is solely to upgrade the currently running Tableau Server in a Container.

Follow the below steps to do the upgrade.

1. Create an upgrade-image using the build-upgrade-image script. The new version's tableau server rpm is needed to build this container.
2. Shut down the container currently running the Tableau Server.
3. Start the upgrade-image, mounting the same data directory from the container shutdown in the previous step.
4. The upgrade process takes a while, but the tableau server will be upgraded. Check docker logs for upgrade process update. The container will shut down after the upgrade process.
5. Start a new Tableau Server in a Container of newer version. Mount the same directory from the previous steps.

Example:

Let's say we have a Tableau Server in a Container running Tableau Server. Here are some assumptions made in this example:

• I have valuable data, and I don't want to lose any data during the upgrade process. The data directory needs to be persisted outside the container.
• The container is named my-server. The docker image is named as tableau-server:versionA.
• The server version my-server is currently using version A.
• The server version I want to upgrade to is version B.

1. Get tableau server rpm for version B. Create an upgrade-image.

   # For all the options available in the script
   ./build-upgrade-image -h
    
   # Frequently used command to create a upgrade-image
   ./build-upgrade-image --installer=<path to the tableau server version B> -i tableau-server:versionA -o tableau-server-upgrade:versionAB

2. Stop the my-server container.

   docker stop my-server -t 120

3. Start the newly created image tableau-server-upgrade:versionAB. Mount the same data directory from the previously stopped container. The container starts the upgrade process to version B.

   docker run --name my-upgrade-server \
   -v <data-dir mount from previous step>:/var/opt/tableau \
   ...
   tableau-server-upgrade:versionAB

4. The container will stop once the upgrade is complete. Check the docker logs for upgrade process logs and make sure the upgrade process is a success. You can also check the exit code of the docker container to make sure the upgrade process is completed successfully.

   # The log file /var/opt/tableau/tableau_server/logs/upgrade-console.log is created after 3-4 mins into the start of upgrade container. When the upgrade completes successfully, "upgrade is complete" log will be # seen.
   docker logs my-upgrade-server
   ...
   ...
   Verifying licensing state.
   Tableau Server has been upgraded to version near.20.0801.1050.
   >> The upgraded Tableau binary directory will be added to PATH for new shells. To get the
   >> updated path, either start a new session, or for bash users run:
   >> source /etc/profile.d/tableau_server.sh
   Starting service...
   Starting service...
   Job id is '12', timeout is 30 minutes.
   Service was started successfully.
   Status: RUNNING
   Tableau Server is Running
   upgrade is complete

5. Stop the my-upgrade-server container. Start the new version B of Tableau Server in a Container image and mount the data directory from the stopped my-upgrade-server container

   # Stop the server.
   docker stop my-upgrade-server -t 120
   
   
   # Run the new version Hu
   docker run --name my-upgraded-server \
   -v <data-dir mount from previous step>:/var/opt/tableau \
   ...
   ...
   tableau-server:versionB

Upgrading through Backup-Restore method

Follow the steps in the Backup and Restore Section of this document. The only adjustment needed to change a backup-restore operation into an upgrade operation is to restore the backup on a new version of Tableau Server.

Multi-node Tableau Server in a Container

Multi-node Tableau Server in a Container refers to a single deployment of Tableau Server distributed across multiple nodes. Multi-node in this context is the same as Tableau Server multi-node, where certain processes can be run on other nodes to increase capacity, compute power, etc. This is distinct from starting up multiple individual instances of Tableau Server in a Container where each container is an independent server with its own distinct data.

Multi-node Tableau Server in a Container works much like a non-container Tableau Server multi-node installation, and uses the same underlying mechanism. To get an overview of setting up a non-container Tableau Server multi-node installation, see Distributed and High Availability Tableau Server Installations.

Here is an example:

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=<static (internal) 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=<static (internal) 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=<static (internal) name of host machine> \
-d <Tableau Server in a Container image ID or tag>

Exposing Licensing and TSM ports

In order for worker nodes to communicate with the primary instance, we need to open up additional ports. You will need to allow traffic from other nodes on your primary Tableau Server in a Container instance in the following port ranges:

Service Ports: 8800-9000
Postgres Port: 8060
Licensing Ports: 27000-27010

Be careful how many ports you open: We recommend exposing only 200 ports, 8800-9000, instead of the Tableau Server default port range of 8000-9000, because exposing 1000 ports in Docker can negatively impact the performance and start-up time of the Docker image. You can use a smaller or larger port range depending on how complex your Tableau Server topology is. Generally we do not recommend exposing fewer than 100 ports, otherwise you run the risk of services in a cluster being unable to talk to certain services. If you specify your own port range, make sure you expose port 8850 (this is implicitly included in the 8800-9000). The port range is specified by setting the PORT_RANGE_MIN and PORT_RANGE_MAX environment variables.

Additional nodes will also need to expose the Service Port range (8800-9000), but not the Licensing Port range. It is important to note that these port ranges are only to allow Tableau Server inter-process communication. These ports should not be exposed to users or any other machines other than computers that are running Tableau Server in a Container for the same multi-node cluster.

These port rules are consistent with Tableau Server firewall documentation. For more information, see Configure Local Firewall.

Resolving Hostnames

The multiple nodes of Tableau Server in a Container need to be run with consistent hostnames because Tableau Server does not handle dynamic hostname changes. When running Tableau Server multi-node, those nodes will want to communicate with each other. Tableau Server nodes will attempt to reach each other using the hostnames that multi-nodes' Tableau Server in a Container are configured to use. For example, if you run your initial node with a hostname of "initial", additional nodes will attempt to send traffic to a host called "initial". There are multiple ways you can configure images to resolve hostnames to other images. /etc/hosts file in each container to map the arbitrary container hostname (i.e. "initial") to the IP address that is actually running the other container.

Bootstrapping additional nodes

The initial Tableau Server container that runs as part of a cluster generates a bootstrap file that subsequent additional nodes need to use to join the cluster. After additional nodes are registered to the cluster's topology you can start assigning Tableau Server processes to run on them. This process can be fully automated. If you have provided a Tableau Server configuration file (commonly supplied by mounting a configuration file to the file path specified by CONFIG_FILE, default path: /docker/config/config.json) that specifies a Multi-node topology, the initial node will automatically wait until all additional nodes have registered. Once registered, the Multi-node topology will be applied across the cluster.

Once the initial node in Tableau Server in a Container is fully running Tableau Server you can have it generate a bootstrap file for additional nodes:

docker exec -it <container-name> tsm topology nodes get-bootstrap-file -f $BOOTSTRAP_FILE

This command is automatically called for you if you set the value of ALWAYS_WRITE_BOOTSTRAP_FILE to 1.

Security Considerations

The bootstrap file contains server secrets that allow it to establish a TSM session with the initial node. This means if a malicious user obtained the file they could send TSM commands to the server for a period of time. The file itself also contains data that would enable the decryption of server configuration secrets. This file should be treated as sensitive and should be accessible only by services and systems directly pertaining to establishing a multi-node deployment.

Bootstrap Expiry

Bootstrap files carry a limited-time session that lasts for 2 hours. In that window the additional nodes will not need to supply credentials to the initial node in order to join as an additional node. It is possible to use a bootstrap file once the session has expired. However, it would mean needing to supply credentials to the initial node.

Transferring the Bootstrap File

The bootstrap file needs to be made available to and consumed by worker nodes' Tableau Server in a Container. The bootstrap file will need to be shared with all other nodes' instances of Tableau Server in a Container that you want to set as worker nodes for this deployment. This can be done in many different ways.

Transfer the file over a secure network

Part of your automation on the initial node can involve sending the file directly to additional nodes. This should be done using some secure file transfer client/tool. This is probably more useful in scenarios where multiple bootstrap files may be generated throughout the life of the initial node (possibly to add more additional nodes at a later time).

Use a network file mount

A network file mount shared by all the containers in a given deployment is another option.

Other

The end goal is to securely transfer a file produced by one container and transfer it to a specific set of other containers. So any method that achieves this and is secure is sufficient.

Starting additional nodes

To start up a Tableau Server in a Container additional node, simply start the container with the BOOTSTRAP_INSTALL environment variable set to 1.

This will tell the Tableau Server in a Container instance to sleep until a bootstrap file exists at the path specified by the BOOTSTRAP_FILE environment variable (which is also configurable). Refer to the environment variable table to view the default file path. To clarify, if you run a Tableau Server in a Container image in "additional node mode", the container will not start supervisord or any other process other than a bash script running as pid 1 that checks every 5 seconds to see if the bootstrap file exists. Once the file is present, the Tableau Server in a Container will proceed to initialise as an additional node.

Configuring additional nodes

Configuring additional nodes to run a specific topology works the same as it does in a normal Tableau Server deployment. It also comes with the same requirements, which means adding new processes on a node may require a cluster-wide restart. For more information, see Configure Nodes.

Tableau Server Feature Considerations

Some Tableau Server features work differently in containers. This section covers specific features that have special or different considerations in a container environment.

Active Directory

Set AD Domain Controller

If you plan on using Active Directory as an Identity Store for Tableau Server web pages and sites, there is an additional consideration to account for. Tableau Servers running in Linux environments dynamically determine which AD Domain Controller to communicate with by examining their IP subnet. Containers can be assigned arbitrary IP addresses, and in this case Tableau Server will not necessarily be able to use its IP address to find an appropriate domain controller. For this reason it may be necessary to configure a specific domain controller/hostname for Tableau Server to communicate with. To do this follow these steps:

1. Determine which domain controller you want Tableau Server to use and get the hostname.

2. Set the configuration key wgserver.domain.ldap.hostname to the hostname using the standard Tableau Server Admin configuration options:

   • Set the value in the json configuration file CONFIG_FILE.

   • Use the TSM configuration command

     tsm configuration set -k wgserver.domain.ldap.hostname -v <hostname>

Import AD certificate to Tableau Server Keystore

By default Tableau Server in a container communicates with AD via StartTLS whenever simple bind is used. So when the container is run in this configuration, it is necessary to import the AD server certificate to the Tableau Server Keystore, otherwise, server initialisation will fail. To do this follow these steps:

1. Create a pre-init-command script (check Pre-initialisation script section). Add the following line to add the AD certificate to tableau server keystore.

   ${INSTALL_DIR}/packages/repository.${SERVICE_VERSION}/jre/bin -importcert -noprompt -alias startTlsCert -file <mounted-certificate-path> -storetype JKS -storepass changeit -keystore ${DATA_DIR}/config/tableauservicesmanagerca.jks

2. Mount the AD server certificate at the file path provided for -file parameter in the pre-init-command script.

Alternatively, the default setting to communicating with AD via StartTLS can be disabled. Set wgserver.domain.ldap.starttls.enabled to false to disable the StartTLS. But it is not recommended.

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=<static (internal) 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=<static (internal) 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=<static (internal) name of host machine> \
-d <Tableau Server in a Container image ID or tag>

Externalise Data Usage

docker run \
-v <empty-data-dir>:/var/opt/tableau \
-e LICENSE_KEY=<key> \
--hostname=<static (internal) name of host machine> \
-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=<static (internal) name of host machine> \
-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=<static (internal) name of host machine> \
-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>