<!-- Source: https://docs.squirro.com/en/latest/technical/admin/configuration/pdf-viewer.html -->
# PDF Viewer

## Overview

Starting with Squirro 3.15.4, the built-in PDF viewer is powered by [Nutrient](https://www.nutrient.io/) (formerly PSPDFKit). This new viewer improves rendering fidelity, search highlighting accuracy, and performance for large documents.

The Nutrient PDF viewer requires a valid license key to operate. Without a license key, PDF documents are still rendered, but each page is displayed with a watermark.

> **Note**
>
> Existing customers upgrading to Squirro 3.15.4 (or later) must obtain a license key and configure it before the new PDF viewer will operate without a watermark. The PDF viewer also requires additional [Content Security Policy](secure-config-guide.md#admin-csp-minimal-policy) directives to load correctly.

## Obtaining a License Key

Squirro provides the Nutrient PDF viewer license key to customers as part of their Squirro subscription.

Nutrient license keys are domain-locked, meaning each key is valid only for the specific domains it was issued for. When requesting a key, include the full list of domains on which Squirro is deployed (for example, `app.example.com` and `staging.example.com`). Providing all domains upfront avoids delays caused by follow-up requests.

> **Note**
>
> Wildcard keys (`*.squirro.com`, `*.squirro.net`, `*.squirro.cloud`) already exist for deployments under these Squirro-managed domains. If your instance runs under one of those domains, request the existing key rather than a new one. Keys for `localhost` and `127.0.0.1` are also available for local development setups.

To request a license key, visit the [Squirro Support website](https://go.squirro.com/support) and submit a technical support request. Once you have received the license key, apply it using one of the methods described below.

## Applying the License Key

There are two supported ways to apply the license key to a Squirro instance, depending on whether the deployment is managed via Ansible.

### Option 1: Ansible-Managed Deployments (Recommended)

For deployments managed via the `squirro-ansible` role, ensure the role is updated to a version that supports the [`nutrient_pdf_viewer_license_key`](../../../getting/install/ansible/variable-reference.md#confval-nutrient_pdf_viewer_license_key) variable, then set the variable to the license key value provided by Squirro.

```yaml
nutrient_pdf_viewer_license_key: "YOUR_LICENSE_KEY"
```

Re-run the role against the target instance. The license key is written to `/etc/squirro/frontend.ini` under the `[nutrient_pdf_viewer]` section.

> **Note**
>
> On Squirro 3.15.4 and later, the Ansible role fails fast if [`nutrient_pdf_viewer_license_key`](../../../getting/install/ansible/variable-reference.md#confval-nutrient_pdf_viewer_license_key) is unset or empty. For full variable details, see the [Ansible Role Variables Reference](../../../getting/install/ansible/variable-reference.md#ansible-variable-reference) page.

### Option 2: Manual Configuration

For deployments not managed via Ansible, or as a temporary workaround until the Ansible role is updated, set the license key manually in `/etc/squirro/frontend.ini`:

```ini
[nutrient_pdf_viewer]
license_key = YOUR_LICENSE_KEY
```

After saving the file, restart the frontend service for the change to take effect. For broader guidance on managing configuration files securely, see the [PDF Viewer License Key](secure-config-guide.md#admin-pdf-viewer-license) section of the [Secure Configuration Guide](secure-config-guide.md#admin-secure-config-guide).

## Content Security Policy

The Nutrient PDF viewer relies on Web Workers, blob URLs, and WebAssembly, all of which require explicit Content Security Policy (CSP) directives. If your deployment sets a custom CSP, ensure the following directives are present:

```
worker-src blob:
img-src blob:
script-src 'wasm-unsafe-eval'
```

For the full recommended CSP policy, see the [Recommended Minimal Policy](secure-config-guide.md#admin-csp-minimal-policy) section.