A Latex template to PDF generation web service written in Rust.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
docker
examples
src
tests
.editorconfig
.gitignore
.travis.yml
CHANGELOG.md
CODE_OF_CONDUCT.md
CONTRIBUTING.md
Cargo.lock
Cargo.toml
LICENSE
README.md
RELEASE-CHECKLIST.md
_config.yml
logo.png

README.md

Papers

Papers Logo

Build Status PRs Welcome license

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

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, {{world}}

\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_AWS_ACCESS_KEY

The key will be used for the S3 uploads.

Required.

PAPERS_AWS_SECRET_KEY

The secret key corresponding to PAPERS_AWS_ACCESS_KEY.

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: ""