Papers

A Latex template to PDF generation web service written in Rust. Papers is available as a docker image on Docker Hub. It relies on an installation of xelatex.

Papers uses semantic versioning. So until 1.0.0 is reached expect many breaking changes.

Examples / Documentation

• Simple example
• Papers on Kubernetes
• Merge documents with Papers
• LaTeX + Tera templates tips and tricks

Security

This service is not secure yet so it should not be publicly accessible. An invader could create a template that does bad things with Latex. Therefore, it is recommended to set the PAPERS_BEARER environment variable to a long and arbitrary string and set this string in the Authorization header of every request.

Endpoints

GET /healthz

Returns 200. For liveness probes in Kubernetes.

POST /submit

Headers:

Content-Type: application/json

Example body:

{
  "template_url": "http://example.com/template.tex.tera",
  "asset_urls": [
    "http://example.com/logo.png"
  ],
  "variables": {
    "world": "World"
  },
  "callback_url": "http://example.com/callback"
}

• template_url: The Latex template as a downloadable URL.
• asset_urls: An array of asset URLs that are used in the Latex template. They are downloaded next to the Latex document.
• variables: The variables that are used in the Latex template.
• callback_url: The URL that the final PDF or the error will be sent to.
• no_escape_tex: (Optional) Disable escaping strings from variables for TeX special characters like &, % and $.

POST /preview

Headers:

Content-Type: application/json

Example body:

{
  "template_url": "http://example.com/template.tex.tera",
  "asset_urls": [
    "http://example.com/logo.png"
  ],
  "variables": {
    "world": "World"
  }
}

• template_url: The Latex template as a downloadable URL.
• asset_urls: An array of asset URLs that are used in the Latex template. They are downloaded next to the Latex document.
• variables: The variables that are used in the Latex template.

Example Latex template

The templating language is Tera

\documentclass{article}

\begin{document}
hello, 

\end{document}

Papers registers two custom Tera filters which can be used in your templates:

• unescape_tex: Papers defaults to escaping TeX special characters. This filter will remove the escape backslashes to make the contents of the variable be evaluated as TeX.
• escape_tex: escapes TeX special characters - this is done by default by Papers so it’s only useful combined with the no_escape_tex setting in the POST body.

Local server

Papers ships with the papers local command that you can use to develop your templates locally. Just put your assets in a directory, name your template template.tex.tera, put variables in a variables.json and run the binary. You will get a rendered PDF that is produced by the same code that runs in the service.

Take a look at the simple example in the examples directory for a quick introduction.

Explanation of the environment variables

PAPERS_BEARER

The string that will be checked in the Authorization header.

Default: <empty string>

Example:

PAPERS_BEARER=secret-string
=> Authorization=Bearer secret-string

PAPERS_LOG_LEVEL

The logger level for the Papers service.

Default: info
Other options: debug

PAPERS_PORT

The port the Papers sever runs on.

Default: 8080

PAPERS_MAX_ASSETS_PER_DOCUMENT

The maximum amount of assets per document/request accepted by Papers

Default: 20

PAPERS_MAX_ASSET_SIZE

The maximum size of assets in bytes (or with K, M or G suffix).

Default: 10M

PAPERS_ACCESS_KEY_ID

The key will be used for the S3 uploads.

Required.

PAPERS_SECRET_ACCESS_KEY

The secret key corresponding to PAPERS_ACCESS_KEY_ID.

Required.

PAPERS_S3_BUCKET

The S3 bucket where generated documents and debug output should be uploaded.

Required.

Example: my-company-name-papers

PAPERS_AWS_REGION

The AWS region the bucket belongs to.

Required.

Example: eu-central-1

PAPERS_S3_EXPIRATION_TIME

The expiration delay on the presigned urls returned to the callback url, in seconds.

Default: 86400

SENTRY_DSN

This is for tracking errors with sentry.io. If left blank, nothing will happen.

Default: ""