## Set up on-premises Tableau access

URL: https://docs.atlan.com/apps/connectors/business-intelligence/tableau/how-tos/set-up-on-premises-tableau-access

> In some cases you may not be able to expose your Tableau instance for Atlan to crawl and ingest metadata. For example, this may happen when security requirements restrict access to sensitive, mission-critical data.

:::danger **Deprecated**
This job execution mode was deprecated on June 30, 2026 and is no longer supported or maintained, including bug fixes. Existing workflows may break/be disabled without warning. For all implementations, switch to [Self-deployed runtime](https://docs.atlan.com/llms/platform/self-deployed-runtime/llms.txt).
:::

:::warning Who can do this?
 You will need access to a machine that can run Docker on-premises. You will also need your Tableau instance details, including credentials.

:::

In some cases you may not be able to expose your Tableau instance for Atlan to crawl and ingest metadata. For example, this may happen when security requirements restrict access to sensitive, mission-critical data.

In such cases you may want to decouple the extraction of metadata from its ingestion in Atlan. This approach gives you full control over your resources and metadata transfer to Atlan.

## Prerequisites

To extract metadata from your on-premises Tableau instance, you will need to use Atlan's tableau-extractor tool.

:::info **Did you know?** 
 Atlan uses exactly the same tableau-extractor behind the scenes when it connects to Tableau in the cloud.

:::

### Install Docker Compose

[Docker Compose](https://docs.docker.com/compose/) is a tool for defining and running applications composed of many [Docker](https://docs.docker.com/get-started/overview/) containers. (Any guesses where the name came from? 😉)

To install Docker Compose:

1. [Install Docker](https://docs.docker.com/get-docker/)
2. [Install Docker Compose](https://docs.docker.com/compose/install/)

:::info **Did you know?** 
 Instructions provided in this documentation should be enough even if you are completely new to Docker and Docker Compose. However, you can also walk through the [Get started with Docker Compose](https://docs.docker.com/compose/gettingstarted/) tutorial if you want to learn Docker Compose basics first.

:::

### Get the tableau-extractor tool

To get the tableau-extractor tool:

1. [Raise a support ticket](https://docs.atlan.com/support/submit-request) to get the link to the latest version.
2. Download the image using the link provided by support.
3. Load the image to the server you'll use to crawl Tableau:

 ```
 sudo docker load -i /path/to/tableau-extractor-master.tar
 ```

## Get the compose file

Atlan provides you with a [Docker compose file](https://docs.docker.com/compose/compose-file/) for the tableau-extractor tool.

To get the compose file:

1. Download the [latest compose file](https://atlan-public.s3.eu-west-1.amazonaws.com/atlan/tableau-extractor/docker-compose.yaml).
2. Save the file to an empty directory on the server you'll use to access your on-premises Tableau instance.
3. The file is `docker-compose.yaml`.

## Define Tableau connections

The structure of the compose file includes three main sections:

- `x-templates` contains configuration fragments. You should ignore this section - do not make any changes to it.
- `services` is where you will define your Tableau connections.
- `volumes` contains mount information. You should ignore this section as well - do not make any changes to it.

### Define services

For each on-premises Tableau instance, define an entry under `services` in the compose file.

Each entry will have the following structure:

```
services:
 connection-name:
 <<: *extract
 environment:
 <<: *tableau-defaults
 EXCLUDE_PROJECTS_REGEX: "Test1.*|Test2.*"
 CRAWL_UNPUBLISHED_WORKSHEETS_DASHBOARDS: "true"
 CERT_PATH: ""
 volumes:
 - ./output/connection-name:/output/process
```

- Replace `connection-name` with the name of your connection.
- `<<: *extract` tells the tableau-extractor tool to run.
- `environment` contains all parameters for the tool.
- `CERT_PATH` - if applicable, specify the [SSL certificate](https://docs.atlan.com/llms/catalog/connector-capabilities/provide-ssl-certificates/llms.txt) path and store it as a new volume.
- `volumes` specifies where to store results. In this example, the extractor will store results in the `./output/connection-name` folder on the local file system.

You can add as many Tableau connections as you want.

:::info **Did you know?** 
 [Docker's documentation](https://docs.docker.com/compose/compose-file/#services-top-level-element) describes the `services` format in more detail.

:::

## Provide credentials

To define the credentials for your Tableau connections, you will need to provide a Tableau configuration file.

The Tableau configuration is a `.ini` file with the following format:

```
[TableauConfig]

# Tableau instance URL. Do not include /api/* in the URL.

server_url=https://:<hostname>:<port>

# Tableau site name. Leaving this empty will select the default site.

site_name=YourTableauSite

# Tableau authentication type. Options: basic, personal_access_token.

auth_type=basic

# Required only if auth_type is basic.

[BasicAuth]
username=YourTableauUsername
password=YourTableauPassword

# Required only if auth_type is personal_access_token.

[PersonalAccessTokenAuth]
token_name=YourTableauTokenName
token_value=YourTableauTokenValue
```

:::warning

For basic authentication, ensure that your password does not contain the special character `%`. If the percent sign is included in your password, add another `%` to escape it.

:::

## Secure credentials

### Using local files

:::warning

If you decide to keep Tableau credentials in plaintext files, we recommend you restrict access to the directory and the compose file. For extra security, we recommend you use [Docker secrets](https://docs.docker.com/engine/swarm/secrets/) to store the sensitive passwords.

:::

To specify the local files in your compose file:

```
secrets:
 tableau_config:
 file: ./tableau.ini
```

:::warning

This `secrets` section is at the same top-level as the `services` section described earlier. It is not a sub-section of the `services` section.

:::

### Using Docker secrets

To create and use Docker secrets:

1. Store the Tableau configuration file:

 ```
 sudo docker secret create tableau_config path/to/tableau.ini
 ```

2. At the top of your compose file, add a [secrets](https://docs.docker.com/compose/compose-file/compose-file-v3/#secrets-configuration-reference) element to access your secret:

 ```
 secrets:
 tableau_config:
 external: true
 name: tableau_config
 ```

 - The `name` should be the same one you used in the `docker secret create` command above.
 - Once stored as a Docker secret, you can remove the local Tableau configuration file.
3. Within the `service` section of the compose file, add a new secrets element and specify the name of the secret within your service to use it.

## Example

Let's explain in detail with an example:

```
secrets:
 tableau_config:
 external: true
 name: tableau_config

x-templates:
 # ...

services:
 my-tableau:
 <<: *extract
 environment:
 <<: *tableau-defaults
 EXCLUDE_PROJECTS_REGEX: "Test1.*|Test2.*"
 CRAWL_UNPUBLISHED_WORKSHEETS_DASHBOARDS: "true"
 CERT_PATH: "/tmp/tab-cert.pem"
 volumes:
 - ./output/my-tableau:/output/process
 - ./tab-cert.pem:/tmp/tab-cert.pem
 secrets:
 - tableau_config
```

1. In this example, we've defined the secrets at the top of the file (you could also define them at the bottom). The `tableau_config` refers to an external Docker secret created using the `docker secret create` command.
2. The name of this service is `my-tableau`. You can use any meaningful name you want.
3. The `<<: *tableau-defaults` sets the connection type to Tableau.
4. `EXCLUDE_PROJECTS_REGEX` tells the extractor to filter out all the projects whose names match the `Test1.*` and `Test2.*` regex patterns in the extracted metadata.
5. `CRAWL_UNPUBLISHED_WORKSHEETS_DASHBOARDS` tells the extractor to include all hidden or unpublished worksheets and dashboards that are part of a Tableau workbook in the extracted metadata.
6. `CRAWL_EMBEDDED_DASHBOARDS` tells the extractor to create relationships between Tableau dashboards used within another dashboard as a *Web Page* item.
7. The `CERT_PATH` tells the extractor where to store the [SSL certificate](https://docs.atlan.com/llms/catalog/connector-capabilities/provide-ssl-certificates/llms.txt), if applicable. In this example, the extractor will store results in the `./tab-cert.pem` directory on the local file system. If the SSL certificate is not stored in the same folder as the compose file, you will need to specify the full path.
8. The `./output/my-tableau:/output/process` line tells the extractor where to store results. In this example, the extractor will store results in the `./output/my-tableau` directory on the local file system. We recommend you output the extracted metadata for different connections in separate directories.
9. The `secrets` section within `services` tells the extractor which secrets to use for this service. Each of these refers to the name of a secret listed at the beginning of the compose file.

---