Install Bridge for Linux for Containers

Applies to: Tableau Cloud

Bridge for Linux provides the scalability and streamlined management capabilities of containerised workloads. The following instructions describe a lightweight way to run Bridge for Linux and assumes you have basic knowledge of Docker and the key terms used in the ecosystem.

Install and run Bridge from a Docker container

To use Bridge on Linux, you must create a customised Docker image, install the RPM package and then run Bridge from inside the container image.

Prerequisites

  • Installed Docker Engine. For the base image of the docker container, Bridge on Linux is supported on:
    • Amazon Linux 2
    • Amazon Linux 2023
    • Red Hat 8.3 and higher

      Note: CentOS is not supported.

  • The latest Tableau Bridge RPM package from the Downloads(Link opens in a new window) page on the Tableau website.
  • Experience with the Linux operating system.
  • Basic shell scripting.
  • Docker experience.
  • Tableau Site admin Personal Access Token (PAT). We recommend that you use one PAT token per Bridge client.

Step 1: Create a Bridge container image

The following steps are the basic instructions for building a Bridge on Linux base image. For more information, see Docker overview.

When Docker is installed, the only user with permission to run commands is root. You can run Docker commands with sudo or by a user who is a member of the docker group.

  1. Download the Bridge.rpm package from the Downloads(Link opens in a new window) page on the Tableau website.
  2. (Optional) You can edit the configuration settings to change how the client will run. See Change the Bridge Client Settings for more information.
  3. Create a working directory and move the .rpm package into the directory.

    cd ~

    $ mkdir Docker

    $ cd Docker

    $ mv <RPM_location>.rpm .

  4. Create a Docker file in the working directory. For example:

    $ touch Dockerfile

  5. Edit the Docker file and add the commands to run yum update.

    Red Hat Example

    For Red Hat 8:

    FROM registry.access.redhat.com/ubi8/ubi:latest

    RUN yum -y update

  6. Edit the Docker file and then enter the commands to copy, install and remove the bridge RPM package from the image. For example:

    COPY <your_bridge_rpm>.rpm /<path_of_container>

    RUN ACCEPT_EULA=y yum install -y $(find . -name *.rpm) && rm -rf *.rpm

  7. Build a new container image using the docker build command.

    For example, the following command builds an image in the current directory, tagging it with the word ​"bridge_base":

    docker buildx build --platform=linux/amd64 -t bridge_base .

  8. Check that the base image you created is displayed in the list of images:

    docker images | grep bridge

Step 2: Install the drivers

The Bridge client requires drivers to facilitate connectivity between private network data and Tableau Cloud. For drivers, go to Driver Download, select the data source and then select Linux for the Operating system.

  1. Installation can be done interactively after the base image is launched, or separate Dockerfiles can be written as a layer on top of the base image.

    Example

    With the MySQL driver RPM copied into the directory, you can create a separate working directory for layering MySQL drivers using the following Dockerfile:

    # Using previously built bridge_base image

    FROM bridge_base COPY mysql-connector-odbc-8.0.26-1.el7.x86_64.rpm .

    RUN yum install -y mysql-connector-odbc-8.0.26-1.el7.x86_64.rpm

    Example

    Install a postgres JDBC driver. This can also be done in a separate Dockerfile.

    # Using previously built bridge_base image

    FROM bridge_base COPY postgresql-42.3.3.jar /opt/tableau/tableau_driver/jdbc/

    Example

    Install the Amazon Redshift driver.

    # Using previously built bridge_base image

    FROM bridge_base

    yum install -y unixODBC

    yum --nogpgcheck localinstall -y

    AmazonRedshiftODBC-64-bit-1.4.59.1000-1.x86_64.rpm

    odbcinst -i -d -f /opt/amazon/redshiftodbc/Setup/odbcinst.ini

  2. Create a new image:

    3. docker image build -t bridge_final .

    The bridge_final image uses the cached image from the previous step and automates the driver installation for all your Bridge instances. If you have an image repository, you can publish the image to the repository and distribute the image to all the machines you want to run Bridge on.

Step 3: Run the Bridge container

Now that you have a base image built, you can deploy it using a variety of methods. The basic steps are:

  1. Start the instance of the Bridge container.
  2. Log in and start the worker.
  3. Assign the agent to a pool.

Note: Bridge for Linux doesn't support Bridge (legacy schedules). See Migrate from Bridge (legacy) to Online schedules for more information.

  1. Before you start deploying the container, create a Personal Access Token (PAT). The PAT is required to log in to the agent. Tableau Cloud supports 104 PATs per user. We recommend that you use one PAT token per client.

    Note: The following token names must match: The patTokenId (used when running the run-bridge.sh command), the token name in the JSON file and the token name when generating the PAT in Tableau Cloud.

  2. Set the locale in Docker using ENV LC_ALL en_US.UTF-8. You can also set the locale by adding the following to the /etc/profile file:

    3. export LANG="en_US.utf8"

    export LANGUAGE="en_US.utf8"

    export LC_ALL="en_US.utf8"

  3. Start an instance of the Bridge container. There are many ways you can set up and start the container image. The following interactive method illustrates the steps necessary to start the worker. When you exit, the container stops running.
    1. Use the following method to move to the shell prompt for the container as root. The rest of the commands are executed in the context of this interactive session of the container.

      docker container run -it bridge_final /bin/bash

    2. Add the PAT token to a flat file in JSON format. For example:

      /home/jSmith/Documents/MyTokenFile.txt

      3. Example token syntax:

      {"MyToken" : "uLICC7e8SUS8ZNGe8RIFn4u==:lRihmYHI0XBKle7e8S4uSORXGqAkAl4"}

    3. Change the file permissions to restrict access to the current user. For example:

      chmod 600 MyTokenFile.txt

    4. Start the worker with the run-bridge.sh command and provide the following command options:

      CommandDescription
      --patTokenIdThe ID of the PAT. See Personal Access Tokens for more information.
      --userEmailUser email associated with the PAT.
      --clientThe name that you want to give to the Worker.
      --siteSite name as it appears in the URI. Don’t include the URI path.
      --patTokenFileFile name and path to the PAT text file.
      -e(Optional) By default, the Bridge client worker runs as a background service. To run the worker in the foreground, include the -e argument.
      --poolId(Optional) Pool ID that is assigned to the client. See Using a pool ID.

      Command example 

      /opt/tableau/tableau_bridge/bin/run-bridge.sh -e --patTokenId="Mytoken" --userEmail="admin@tableau.com" --client="myBridgeAgent" --site="mySite" --patTokenFile="/home/jSmith/Documents/MyTokenFile.txt" --poolId="1091bfe4-604d-402a-b41c-29ae4b85ec94"

      Note: If you are installing older versions of the Bridge for Linux, you must run a different command to start the worker. For versions 2024.2 and older, start the worker with the TabBridgeClientWorker command (not the run-bridge.sh command. All of the command options are the same.

    4. The following message indicates the agent is started. “Service started: ...”

    Use Control-C to stop the worker. Rather than restart the worker, you can start a new worker for the container image.

    If you didn’t assign a pool using the command option --poolId, the client is assigned to the default pool. If you want to use the client with specific domains or VConns, you can assign the client to a named pool using the UI. The menu for this on Tableau Cloud Home > Settings > Bridge. For more information, see Configure the Bridge Client Pool.

Using a pool ID

When starting the Bridge worker with the run-bridge.sh command, the poolId is optional. However, the behaviour of the client depends on whether the client is registered to a site and whether the client is assigned to a pool. Tableau Bridge can only connect or register to one Tableau Cloud site at any given time. The client is registered to a site when you log off and log back in.

If a pool ID isn’t provided

  • If the Bridge client has been registered, the client status remains the same:
    • If the client is assigned to a pool, it remains assigned to the pool, regardless of whether it’s a named pool or default pool.
    • If the client isn’t assigned to a pool, it will remain unassigned.
  • If the Bridge client is new (you never signed in to Tableau Cloud), the client is assigned to the default pool.

If a pool ID is provided

  • If the pool ID is provided and is correct, the Bridge client is assigned to the named pool.
  • If the pool ID is provided and incorrect:
    • If the Bridge client isn’t registered, then the client is assigned to the default pool.
    • If the Bridge client is registered, the client status remains the same, regardless of named pool, default pool or unassigned.

Finding the Pool ID

To find the pool ID, go to the Settings > Bridge page and click on the name of the pool. For example:

Troubleshooting

Installing older versions

If you are installing older versions of the Bridge for Linux, you must run a different command to start the worker. For versions 2024.2 and older, start the worker with the TabBridgeClientWorker command (not the run-bridge.sh command).

All of the command options are the same as documented above in Step 3: Run the Bridge container.

For example: 

/opt/tableau/tableau_bridge/bin/TabBridgeClientWorker -e --patTokenId="Mytoken" --userEmail="admin@tableau.com" --client="myBridgeAgent" --site="mySite" --patTokenFile="/home/jSmith/Documents/MyTokenFile.txt" --poolId="1091bfe4-604d-402a-b41c-29ae4b85ec94"

Worker start-up error

In some cases, the following error will be displayed after running the run-bridge.sh command:

Missing log in parameters. Aborting the attempt to start service worker.

In most cases, re-running the command with the original options and the -e option fixes the issue. The -e option runs the Bridge worker service in the foreground.

Working with log files

Log files are stored in the user's My_Tableau_Bridge_Repository/Logs folder. To save logs in a tmp folder, run the following command:

docker container run --volume /tmp/bridge_logs:/root/Documents/My_Tableau_Bridge_Repository/Logs -it bridge_final /bin/bash

In this example, the location is specified by /tmp/bridge_logs. Using the docker command simplifies saving the log files and avoids having to manually copy the Bridge logs files from the container to your local file system.

MySQL driver fails

If LC_MESSAGES aren’t set with UTF-8 locales, you may experience read and display issues. You can edit the /etc/profile file, or relaunch the worker using the following command:

LC_ALL=en_US.UTF-8 /opt/tableau/tableau_bridge/bin/run-bridge.sh -e

Bridge Client stops unexpectedly due to Personal Access Token expiry

When a Personal Access Token (PAT) expires, it will cause the Bridge Client to become disconnected from Tableau Cloud and may cause the container to shut down. From the Bridge Client, you can validate if your PAT has expired by executing the Start command in the foreground. If the PAT has expired, you will see the following error:

The client credentials are invalid. To complete the request, reset the credentials, and sign in to the Tableau Bridge client.

If you are the original PAT owner, you can also verify if the PAT has expired by visiting Manage Account Settings in Tableau Cloud. To resolve the issue, you will need to generate a new PAT and follow the steps above, Step 3: Run the Bridge container.

Embedded extract and embedded live connection timeout errors

The 24.3 release of Bridge on Linux provided significant performance improvements for embedded extracts and embedded live connections. If you experience timeout errors on prior releases, we recommend upgrading to a 24.3+ release of Bridge on Linux. If this does not resolve the issue, publish the data source separately from the workbook.

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