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 (on premis), 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 internet 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/CLOUD extension model (Create & Share subscriptions)

The architecture of Share Subscriptions to deploy extensions for Tableau

On Premise extension model (Enterprise subscriptions)

The architecture of Enterprise (on-premise or private cloud) Subscriptions to deploy extensions for Tableau More information on our premium Tableau dashboard extensions can be found at: https://appsfortableau.infotopics.com/support/documentation

Infrastructure requirements

Our Enterprise extensions for Tableau are available as a Windows or Linux Binary with a simple command line startup command as can be read further in this installation manual. There are some requirements and specifications to be met before you start. Most important requirements up front are listed below:
 
General Requirements:
  1. A webdomain, for example: https://extension.company.com  (create a DNS entry)
  2. SSL certificates for above domain (the installation requires the domain’s .crt and private .key file)
  3. Domain from step 1 needs to point to the IP address of the server to install the extension server using DNS (internal and/or external)
  4. Server Resources: 4 vCPU, 8Gb, 50Gb application diskspace, 100Mbps or 1Gbps network-interface
  5. Firewall rules to permit access on port 443 (https) to the server (or any other port you configure in the startup commands of the extension server). Both internal, external and server-firewall.
What does the installation look like The enterprise installation package contains 3 files.

  1. “extension-name.exe” for Windows or “extension-name” for Linux (where extension-name is replaced by the name of the extension).
    • This (Windows or Linux) binary is the Extension server that hosts the server part of the extension in your infrastructure. The binary has several option flags to start/configure the server (double -):
      • –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 folder as the extension binary. 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 binary 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 trex 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. First you need to comply to the requirements from this step so you need a domain name (url) that points to the IP address of the machine where you want to install the extension server. You also need the ssl certificate and sll private key file to start with the installation. Second step is to place the files listed above and the ssl certificate and private key file in a folder on the machine where you want to install the extension server. Third step is to use the command line to start the extension server Fourth step is to edit the trex file

The binary file 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 binary to use https directly or place it behind a reverse proxy that handles the https. The binary should preferably be configured to launch on server start-up. To run the binary as a user (for test or evaluation purposes for example), open a command prompt in the same folder as the binary and use the following command:

Windows:
./extension-name.exe --port 4000 --cert ./certificate.crt --key ./certificate.key
Linux:
./extension-name --port 4000 --cert ./certificate.crt --key ./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). Make sure to use double dashes (- -) for commands.

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” binary 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.

Windows

The easiest way to have the extension started automatically as a service is to create a task in Windows Task scheduler. The trigger of the task must be configured to “System boot” and it is best run under System Credentials. Below the steps to follow.
 

1. Start Windows Task Scheduler

 

2. Create a new task

 

3. Enter the general task information

 
  • Name the task with a reference to the extension you will start with this task
  • Set SYSTEM user account to execute this task. It is important to use an account with privelidges to start services
  • Check what version suits your system best (Windows Server)

4. Set trigger for the task to be executed (startup)

  • Add a new trigger on the TASK pane
  • Select the trigger “At Startup”
  • Make sure the trigger is enabled

5. Set the action to start the program

  • On the “Actions” tab select “New…”
  • Set your action to type “Start program”
  • Select the binary file of your extension as the “Program”. In this example it is “C:\SuperTables\super-tables-win.exe”. Make sure to include the entire path
  • Set your Arguments for the extension server (port number and certificate details). In this example: “–port 443 –cert certificate.crt –key certificate.key”
  • Set the “Start in” folder. This is very important for the service to start correctly. It is the path where the binary file/program is located. In this example: “C:\SuperTables\”
  • Press OK to store your “Action”

​6. Set Conditions

  • Make sure the task will always be executed (battery or AC power)
 

​7. Set extra settings

  • Make sure the task will remain running
  • Make sure the task can be started on demand

8. Manual start the task

  • Once you saved the newly created task select it in the list of tasks
  • click the “Run” button on the right panel to start the new task
  • The status of the service will change from “Ready” to “Running” just like the ShowMeMore task in the screenshot.
 

Linux

Create a Custom systemd Service

  1. Create a script or executable that the service will manage. This guide uses a simple Bash script as an example:
    File: test_service.sh

     
    1
    2
    3
    4
    5
    6
    7
    8
    
    DATE=`date '+%Y-%m-%d %H:%M:%S'`
    echo "Example service started at ${DATE}" | systemd-cat -p info
    
    while :
    do
    echo "Looping...";
    sleep 30;
    done

    This script will log the time at which it is initialized, then loop infinitely to keep the service running.

  2. Copy the script to /usr/bin and make it executable:
    sudo cp test_service.sh /usr/bin/test_service.sh
    sudo chmod +x /usr/bin/test_service.sh
    
  3. Create a Unit file to define a systemd service:
    File: /lib/systemd/system/myservice.service
    [Unit]
    Description=Extension Name Service
    After=network.target
    [Service] User=root WorkingDirectory= /usr/local/bin ExecStart= /usr/local/bin/super-tables-linux –port 443 –cert yourdomain.crt –key yourdomain.key Restart=on-abort [Install] WantedBy=multi-user.target

    This defines a simple service. The critical part is the ExecStart directive, which specifies the command that will be run to start the service.

  4. Copy the unit file to /etc/systemd/system and give it permissions:
    sudo cp myservice.service /etc/systemd/system/myservice.service
    sudo chmod 644 /etc/systemd/system/myservice.service

Start and Enable the Service

  1. Once you have a unit file, you are ready to test the service:
    sudo systemctl start myservice
  2. Check the status of the service:
    sudo systemctl status myservice
    

    If the service is running correctly, the output should resemble the following:

    myservice.service - Example systemd service. Loaded: loaded (/lib/systemd/system/myservice.service; enabled; vendor preset: enabled) Active: active (running) since Tue 2018-05-01 18:17:14 UTC; 4s ago Main PID: 16266 (bash) Tasks: 2 Memory: 748.0K CPU: 4ms CGroup: /system.slice/myservice.service ├─16266 /bin/bash /usr/bin/test_service.sh └─16270 sleep 30 May 01 18:17:14 localhost systemd[1]: Started Example systemd service.. May 01 18:17:14 localhost cat[16269]: Example service started at 2018-05-01 18:17:14 May 01 18:17:14 localhost bash[16266]: Looping...
  3. The service can be stopped or restarted using standard systemd commands:
    sudo systemctl stop myservice
    sudo systemctl restart myservice
    
  4. Finally, use the enable command to ensure that the service starts whenever the system boots:
    sudo systemctl enable myservice
    
    Created symlink from /etc/systemd/system/multi-user.target.wants/myservice.service to /lib/systemd/system/myservice.service.
  5. Reboot your Linode from the Linode Manager and check the status of the service:
    sudo systemctl status myservice
    

    You should see that the service logged its start time immediately after booting:

    myservice.service - Example systemd service. Loaded: loaded (/usr/lib/systemd/system/myservice.service; enabled; vendor preset: disabled) Active: active (running) since Wed 2018-05-02 15:03:07 UTC; 48s ago Main PID: 2973 (bash) CGroup: /system.slice/myservice.service ├─2973 /bin/bash /usr/bin/test_service.sh └─3371 sleep 30 May 02 15:03:07 localhost systemd[1]: Started Example systemd service.. May 02 15:03:07 localhost systemd[1]: Starting Example systemd service.... May 02 15:03:07 localhost bash[2973]: Looping... May 02 15:03:37 localhost bash[2973]: Looping...
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” on Windows or Linux)
  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):

Windows
./server-name.exe --port:8000 --cert ./my-certificate.crt --key ./my-certificate.key
Linux
./server-name --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