Customer-hosted installation of rendering software

Go to customer-hosted installation steps

To send or download data in image-based formats, such as PNG or PDF files, and to 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 you’re 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 on this page.

Currently, Chromium is best supported on Ubuntu systems, but we also provide installation instructions for Debian and Amazon Linux. 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 86 or later is required, but the latest version is generally recommended. Chromium rendering will wait for all resources requested by the page to be completed before it sends the "finished" signal that prompts Looker to produce the rendered content. Due to the number and frequency of these resource requests, some networks can falsely flag the requests as malicious, causing them to drop, which will delay your rendered jobs.

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.

Installing Chromium on Ubuntu

Use the sudo command to perform these steps as the Looker user. Do not install Chromium when you are logged in as the root user. If you install Chromium while logged in as the root user, Looker might not be able to execute PDF or PNG rendering.

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.

DISABLE_EXTERNAL_RENDER_ACCESS: Admins of customer-hosted Looker instances or servers that have no external or blocked Internet access should set DISABLE_EXTERNAL_RENDER_ACCESS=true. Typically, the Chromium renderer will wait for all resources that are requested by the page to be completed before the renderer sends the "finished" signal that prompts Looker to produce the content. Some of these requests may be dropped due to lack of connection, resulting in timeouts or very long render times. Setting this environment variable to true prevents the renderer from waiting for all requests to finish. Some map visualizations and some custom visualizations that are installed from the Looker Marketplace may require Internet access.