Puppeteer is an external web service that can be used to generate PDFs from Notebooks created with LabKey ELN. To use this service, you need to obtain the puppeteer
premium module, and configure your LabKey Server as described in this topic.
Setup Puppeteer Service
puppeteer-service is a web service that allows for generation of assets (e.g. PDFs, screenshots) via Puppeteer. This service is built into a Docker image and served via Express.
This service is deployable as a Docker container on either a Linux or OSX host. Docker is required to be installed on the host machine. You can retrieve the latest Docker image from Docker Hub
using the following command:
docker pull labkeyteamcity/lk-puppeteer-service
If you would prefer to build the Docker image you can clone the LabKey puppeteer-service Git repository
and follow the README's instructions for building an image:
git clone email@example.com:LabKey/puppeteer-service.git
This image can then be run in a container:
docker run -i --init --rm --cap-add=SYS_ADMIN -p 3031:3031 --name puppeteer-service labkeyteamcity/lk-puppeteer-service
A simple HTML view has been added to allow for interacting with the service. To see this view navigate to http://localhost:3031
to get familiar.
Deploying this service on a Windows host is not supported nor tested.
POST to /pdf:
- inputURL: The URL of the website to create a PDF or screenshot from.
- apiKey: (Optional) If visiting a LabKey site that requires credentials you can specify an apiKey.
- fileName: (Optional) Name of the file that is streamed back in the response. Defaults to generated.pdf.
- printFormat: (Optional) Currently supports Letter and A4 page sizes. Defaults to Letter.
- printOrientation: (Optional) Supports Portrait and Landscape orientations. Defaults to Portrait.
Configure Puppeteer Module
- Select (Admin) > Site > Admin Console.
- Under Configuration, click Puppeteer Service.
- Set the properties following the guidance below.
The puppeteer module has two configuration modes for the puppeteer-service. These modes are:
- remote: (Recommended) Remote mode configures LabKey Server to communicate with a remote instance of the puppeteer-service. The service is treated strictly as an external web service where the LabKey Server instance does not manage the service in any way.
- docker: (Experimental) Docker mode leverages LabKey's docker module to configure and run a puppeteer-service container on the LabKey Server instance. This mode manages the lifecycle of the container (i.e. startup, running, shutdown) which shares computational resources with the LabKey server instance.
Remote mode is recommended for several reasons:
- Computational resources. Having the service running alongside LabKey Server, like it does in docker mode, can consume significant CPU and memory resources due to the overhead of the service as well as Docker.
- The remote puppeteer-service can be stood up once and shared by several LabKey Server instances (e.g. staging, production, etc).
Remote URL (Remote mode only)
The "Remote URL" property specifies the URL where the web service can be found. This is provided by whomever sets up the puppeteer-service instance.
Docker Image (Docker mode only)
Docker mode only. The Docker Image
property specifies the name of the puppeteer-service image that is available on the LabKey Server instance. This image has to be downloaded via docker. See service deployment documentation for how to pull down an image.
Docker Port (Docker mode only)
The "Docker Port" property specifies what host port the service container should be bound to.
All of the properties are also available as LabKey Server Bootstrap Properties. An example properties file (using Docker mode) would look something like:
Export Notebook as PDF
Once configured, you will see a
button in your notebooks. Click and choose Export PDF
Adjust settings including:
- Format: Letter or A4.
- Fit to Page: Check box to automatically scale down any contents wider than the page to fit the width of the PDF.
- Orientation: Portrait or Landscape.
to export to PDF.