You are viewing documentation for Looker 24.6. Click this link to see the most recent documentation.

Customer-hosted installation of rendering software

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

Chromium is already installed for Looker-hosted instances.

Chromium rendering waits 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.

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

Chromium installation requirements and prerequisites

Looker supports release versions of all major enterprise Linux distributions, including Ubuntu, Debian, RedHat, CentOS, and Amazon Linux. This page provides instructions for installing Chromium on Ubuntu, Debian, and RedHat/CentOS/Amazon Linux.

Chromium must be installed 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.

To run Chromium on a Looker instance, Chromium 86 or later is required, but Looker recommends using Chromium 97.x specifically. If your Looker instance is installed on Debian, Chromium requires Debian 9 (stretch) or later.

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.

If your data contains non-English characters, install the Google Noto Fonts package (which is several GB in size) in addition to installing Chromium. To install this font package, run these commands in your command line:

mkdir -p /tmp/fonts
cd /tmp/fonts
curl -O https://noto-website-2.storage.googleapis.com/pkgs/Noto-unhinted.zip
unzip Noto-unhinted.zip
mkdir -p /usr/share/fonts/opentype/noto
cp *.otf *.otc /usr/share/fonts/opentype/noto   # Ignore any *.otc not found errors
mkdir -p /usr/share/fonts/truetype/noto
cp *.ttf /usr/share/fonts/truetype/noto
chmod a+r -R /usr/share/fonts/*/noto
fc-cache -f -v

If successful, then:

cd $HOME
rm -rf /tmp/fonts

Installing Chromium on Ubuntu

The Looker application needs to access Chromium using the chromium command or via a custom path set with the CHROMIUM_PATH environment variable. For Ubuntu installations, you must install the Chromium web browser and then set an alias so that the Looker application can find the installation.

Looker recommends using the sudo command when performing any steps that require elevated permissions. 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
```

To install Chromium, run:

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

Must either alias chromium-browser as chromium or export the CHROMIUM_PATH 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 you set any of the optional 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 chromium --version if you have not set the CHROMIUM_PATH environment variable or $CHROMIUM_PATH --version if you have set the CHROMIUM_PATH environment variable.

Installing Chromium on Debian

Looker recommends using the sudo command when performing any steps that require elevated permissions. 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.

Chromium requires Debian 9 (stretch) or later.

If your Looker instance uses Docker with a bare-bones Debian installation, install procps and ensure you are not running as root.

Fonts must be installed on the system for Chromium to start. You can install fonts using the command line interface by running:
```
apt-get install fonts-freefont-otf
```

To install Chromium, run:

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

After you set any of the optional 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.

Optional Chromium 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.