Customer-Hosted Installation of Rendering Software

To send or download data in image-based formats, such as PNG or PDF files and use features such as Paper size and Expand tables, Looker requires rendering software. This page explains how to install rendering software on a customer-hosted instance of Looker.

Installing Rendering Software to Run Standard Looker Features

The following software needs to be installed to use some Looker features.

Chromium

When scheduling or sending Looks and dashboards, Chromium is required to render these data formats:

For dashboards: PDF, Visualization
For Looks: Visualization, HTML

When downloading data, Chromium is required to render these data formats:

For dashboards: PDF
For Looks: HTML, PNG (Image of Visualization)

The Chromium Project is an open source project started by Google to share the non-proprietary parts of Google Chrome.

If you have a Looker-hosted instance, this software is already installed. If you have a customer-hosted Looker instance, follow the instructions below.

Currently, Chromium is best supported on Ubuntu systems but we also provide installation instructions for Debian in this Help Center article. Make sure you install Chromium into an executable path on the machine that hosts the Looker instance. The Looker application needs to access Chromium using the chromium command or via a custom path set with the CHROMIUM_PATH environment variable.

Chromium 65 or later is required.

If you are installing Chromium on a clustered Looker installation, the Chromium version on each node must be fully identical. Even minor differences, such as different build numbers, can interfere with Looker's rendering capabilities.

To install Chromium on Ubuntu:

Fonts must be installed on the system for Chromium to start. You can install fonts using the command line interface. For example, this command installs the default fonts on Ubuntu 16.04 LTS:
```
$apt-get install fonts-freefont-otf
```

On the command line, enter the following command:

apt-get update && apt-get install -y chromium-browser

Ubuntu may need to either alias chromium-browser as chromium or export the environment variable. To alias chromium-browser as chromium, place the following in the ~/.bashrc file:
```
alias chromium='chromium-browser'
```
To make this alias known to Looker, run this command on the command line:
```
sudo ln -s /usr/bin/chromium-browser /usr/bin/chromium
```
After setting any environment variables, restart the Looker application for them to take effect. You may also need to restart any open terminal sessions, or run source ~/.bash_profile to get the terminal to read the new configuration.
After installing Chromium you should get a valid response from either chromium --version or $CHROMIUM_PATH --version depending on whether you set the environment variable.

Optional Environment Variables:

CHROMIUM_PATH: Path to the Chromium binary, defaults to chromium.
CHROMIUM_PID_DIR: Path to where the library can store Chromium PID files, defaults to chromium_pid_files in the Looker application's working directory.
CHROMIUM_PORT_RANGE_START & CHROMIUM_PORT_RANGE_END: The Chromium application needs a range of ports to communicate between processes on the local machine. The default range is 40000-40500 but you can override this default by setting both of these environment variables. Unused ports are selected at random from the range and are only used for the duration of a single render.

PhantomJS

Starting in Looker 6.18, Looker will no longer support the PhantomJS renderer. We recommend that you install the Chromium renderer to enjoy all of Looker’s rendering capabilities. If you do so, you may need to manually disable the Legacy Rendering legacy feature. See this Community topic for more information about legacy features.

PhantomJS is a headless browser, scriptable with JavaScript, required for rendering image-based data formats.

If your instance is hosted by Looker, this software is already installed. Admins for customer-hosted deployments should follow the instructions below to install PhantomJS.

Make sure you install PhantomJS into an executable path on the same machine as the one on which the Looker instance is hosted. Looker requires PhantomJS 2.1.1+ to run. When upgrading from earlier versions of PhantomJS, you must restart Looker for the new version to be recognized. If Looker detects an older version, it will default to the old behavior where PDFs have one page per visualization instead of the optimized dashboard layout.

To install PhantomJS:

Get the correct binary for your platform from the official PhantomJS repository. PhantomJS is available for Mac, Windows, and various distributions of Linux. For example, the 64-bit Linux version 2.1.1 is:
```
wget https://bitbucket.org/ariya/phantomjs/downloads/phantomjs-2.1.1-linux-x86_64.tar.bz2
```
On Linux, you will need to untar the file. For example:
```
tar -xjf phantomjs-2.1.1-linux-x86_64.tar.bz2
```
Copy the bin/phantomjs binary to a place that is in your system's path. On Ubuntu we recommend /usr/local/bin. For example:
```
mv phantomjs-2.1.1-linux-x86_64/bin/phantomjs /usr/local/bin/
```
Verify that PhantomJS is installed and is the correct version: phantomjs --version
You should now be able to schedule, send, and download data in image-based formats.