Enterprise Installation Guide

///Enterprise Installation Guide
Enterprise Installation Guide 2019-08-30T11:39:09+01:00

Installation Guide

This document describes the installation procedure for the enterprise subscriptions of the AppsforTableau premium dashboard extensions for Tableau.

To work with extensions in Tableau Dashboards you need at least two parts:

1. A webserver capable of running extensions
Extensions are basically web applications that are served by a webserver. By default most extensions connect to a webserver somewhere on the internet. With our Enterprise subscription you get to host the Extension server yourself, which grants you full control of security and access to your data. No internet connections are needed, there is no traffic of data over the internet. You are in full control.

2. The “.trex” Tableau manifest file that you can drag into your dashboard (dashboard object).
This “.trex” file is a XML file containing meta data on the extension and a URL that points your dashboard to the other part that you need when working with extensions; the extension (web)server as explained above this point. By default most third party extensions connect to a webserver somewhere on the internet. With the enterprise subscription you get to host the extension server in your private infrastructure.
In this manual you learn how to install the Extension server in your private infrastructure and alter your “.trex” file to let users connect to your local extension server. Once tested you share or distribute the “.trex” file with your dashboard designers.

AppsforTableau offers two types of subscriptions, the ones using an intertnet connection to the webserver hosting the extension (the extension server) and the subscriptions where you don’t need any connection to the internet (you get to host the extension server in your organizations infrastructure). Below you see two images representing these differences.

SAAS/COUD extension model (Create & Share subscriptions)

Running extensions for Tableau on a Cloud / SAAS basis

On Premise extension model (Enterprise subscriptions)

Running extensions for Tableau on an on premise basis

More information on our premium Tableau dashboard extensions can be found at:
https://appsfortableau.com/support/documentation

The enterprise installation package contains 3 files.

  1. extension-name.exe (where extension-name is replaced by the name of the extension).
    • This executable is the Extension server that hosts the server part of the extension in your infrastructure. The “.exe” has several option flags to start/configure the server:
      • -help: show all available options
      • -port: allows you to configure the port the server runs on
      • -license: path to the license file. By default the extension server uses the file named ‘license.lic’ in the same directory as the extension executable. You don’t have to use this flag on starting up the extension server if you placed the “license.lic” file in the same folder as your extension server (the .exe file). The license file can be stored in another folder, if so you need to use this flag.
      • -cert: path to the TLS certificate to use. Tableau extensions need an ssl connection from the .trex file to the extension server.
      • -key: path to the key file that corresponds to the certificate for the ssl connection.
  2. license.lic
    • The extension license file, without this file the server will only show a warning and the extension will not function.
  1. extension_example.trex
    • The extension trex file that tableau requires to embed the extension in a dashboard.

This file needs to be modified to point to the URL where the “extension-name.exe” is hosting the files. Tableau creators who want to use the extension in a dashboard will need this file.

The executable should preferably run on a server that is accessible to anyone who wants to use the extension in a Tableau dashboard. So all Tableau Desktop Creator users that use the extension in designing their dashboards should be able to connect to the extension server (in your local network).

For Tableau Viewer and Tableau explorer users on the Tableau Server to access published dashboards running the extension, the Tableau Server must be granted access to the Extension server. To learn more on configuring your Tableau Server to run extensions, please read our blog here

Tableau extensions require ssl/https connections from the dashboard to the server. You can either configure the executable to use https directly or place it behind a reverse proxy that handles the https. The executable should be configured to launch on server start-up.

To run the executable as a user (for test or evaluation purposes for example), open a command prompt in the same folder as the executable and use the following command:

.\extension-name.exe -port 4000 -cert ‘C:\path\to\certificate.crt’ -key ‘C:\path\to\certificate.key’

Port 4000 is an example, you can choose another one you like, make sure you also include it in the .trex file (see next steps in this installation guide).

The .trex file is an XML file that can be edited in any plain text editing program.

The following is a copy of the contents of the .trex file with the parts that need to be edited between the tag:

https://local-hostname:4466 should be replaced by the URL of the server the extension-name.exe is running on. Tableau requires extensions to use https. This can also be an IP-address and it can include a port number where the extension listens.

Examples:

https://show-me-more.appsfortableau.com

An internally accessible domain name running on port 443

https://192.168.0.11

An URL using an IP address running on port 443

https://192.168.0.11:4000

An URL using an IP address and an alternative port

The modified “.trex” file can now be tested in Tableau Desktop Creator and, if proven to work correctly, it can be distributed or shared (on a network drive) with the dashboard designers to create beautiful dashboards with the extensions embedded in them.

To run the extension as a service on a server to assure the extension is running even after server reboots follow these steps:

https://www.bogotobogo.com/Powershell/How_to_Run_Exe_as_a_Service_in_Windows_Server_2012.php

The AppsforTableau extensions will continue to develop over time. We will add new functionality, expand possibilities and eliminate bugs. This section will explain how to upgrade your (production) instance of your Enterprise extension server.

The principles of this procedure are:

  • Commands are written for the Windows executable but are equally applicable in Linux environments
  • You have access to the command prompt of the server the AppsforTableau extension server is running on
  • You don’t have to change the trex file already distributed to your users

Just follow these steps:

  1. Login to the machine the extension server is running on
  2. Open a command prompt (Windows Powershell for instance) in the location the Extension server is running
  3. Check on what port the extension is running and where the ssl certificate and key file are located
  4. Stop the running extension server (by pressing “Ctrl C”)
  5. Replace the executable/binary file of the extension server with the new one
  6. Start the new version of the Extension server with the same port number it was running on in the older version

Example powershell command to start the server (replace server-name and my-certificate with the proper filenames and use the correct portnumber that is also in the production version of your trex file):

./server-name.exe --port:8000 -- cert ./my-certificate.crt --key ./my-certificate.key

TIP: Before upgrading your production environment with the new extension server you can testdrive the new version on a different server or your local laptop. To do so, copy the license file, certificate file and certificate key file to a folder, together with the new version of your extension server. Start the new version of the server on your new location (local laptop for instance) and edit the url in a copy of the existing trex file to point to your local new ‘test’ installation. Do not distribute this test-trex file to your production environment users! The url in the test-trex file could for instance be https://127.0.0.1:8000 or https://localhost:8000 when you run it on your laptop on port 8000. Make sure you also install the ssl certificate and key file in this local instance as well since Tableau demands an ssl connection to the extension server!

Test the new version of the extension server with your Tableau Desktop and the test-trex file on your new location. When confident of the result, upgrade your production environment.

By default we distribute a windows binary (.exe file) containing the extension server. You just need a license file (we also provide) and your companies ssl certificate an key file. The extension server is a small webserver to serve Javascript and HTML of the extension. The server does not have to be equipped with a lot of resources. We advice:

  • Windows or Linux Server
  • Fixed IP address
  • Internal DNS
  • At least 8gb RAM
  • 2 cpu or more (preferred)
  • 10 gb hdd space on the server