nebo15/man.api

Template Rendering Engine as a Service

Templates rendering engine microservice

Mán stores templates (in iex, mustache) or markdown documents, renders it over HTTP API with dispatch in PDF, JSON or HTML formats.

"Mán" translates from the Sindarin as "Spirit". Sindarin is one of the many languages spoken by the immortal Elves.

Docs

Full API and installation description available on dedicated page.

Introduction

Man consists of two main parts:

• REST API back-end that allows to manage and render Templates;
• Management UI that simplifies configuration and management.

Use Cases

• Rendering reports;
• Central control over Email or/and SMS templates;
• PDF/HTML printout forms generation;
• Rendering HTML pages over API.

UI

Performance

We encourage you to perform your own tests, because synthetic results are far from real life situation. We provide them only as starting point in understanding Man's performance.

Test environment

• MacBook Pro (15-inch, 2016)
• CPU 2,7 GHz Intel Core i7
• RAM 16 ГБ 2133 MHz LPDDR3
• Man v0.1.16 and PostgreSQL v9.6.2 running in Nebo15 Docker contianers (listed below);
• ApacheBench v2.3;
• wkhtmltopdf v0.12.4 (with patched qt).

Results

Metric/Template Syntax	Mustache	Markdown	Mustache with PDF format	Mustache with PDF format and PDF cache enabled
Concurrency Level	50	50	50	50
Time taken for tests	8.412 sec	8.142 sec	442.214 sec	11.255 sec
Complete requests	10000	10000	10000	10000
Failed requests	0	0	0	0
Requests per second [#/sec] (mean)	1188.84	1228.25	22.61	888.52
Time per request	42.058 [ms]	40.708 [ms]	2211.070 [ms]	56.274 [ms]
Time per request (mean, across all concurrent requests)	0.841 [ms]	0.814 [ms]	44.221 [ms]	1.125 [ms]

Full console output is available in pertest.md.

PDF Output Cache

Since generating PDF is slow, Man allows to cache wkhtmltopdf output.

This cache can be used when you have less than 1000 of different templates variations (eg. markdown templates, or mustache templates but all variables are continuous or enums). To enable it simply set CACHE_PDF_OUTPUT=true in your environment.

Enabling cache when output variety is high will hurt your performance (cache will always be cold, since it's based on HTML checksum) and may lead to node crashes (ETC table may overflow).

Build history

Setup Guide

Application is configured via environment variables. List of supported keys and their default values can be found in docs/ENVIRONMENT.md.

Docker

Easiest way to deploy Man is to use docker containers. We constantly are releasing pre-built versions that will reduce time to deploy:

• Back-End Docker container;
• PostgreSQL Docker container;
• UI Docker container.

Heroku

Template allows to deploy Man to Heroku just in minute (and use it for free within Heroku tiers):

Binary dependencies

wkhtmltopdf is used for HTML to PDF conversion.

License

See LICENSE.md.

man.api's Issues

Render endpoint doesn't accept format in request body

Request

curl -X POST \
  http://35.187.186.145/templates/34/actions/render \
  -H 'content-type: application/json' \
  -d '{
  "name": "Dmitry",
  "format": "text/html"
}'

Response

{
  "type": "content_type_invalid",
  "message": "Content-Type \"*/*\" is not supported",
  "invalid": [
    {
      "entry_type": "header",
      "entry": "Content-Type"
    }
  ]
}

Add new LoggerJSON integration

See example usage in updated renew.

Body Localization

Write docs in Apiary

FE-compatible templating engine

https://github.com/soranoba/bbmustache

Release checklist

Docs:

• Repository has meaningful README.md that describes what service does.
• Service API matches Apiary description.
• If applicable - there are link to Docker Hub.
• (if repo is public) Docker Hub page links to /docs/ENVIRONMENT.md file and repo.
• README.md contains list of third-party dependencies: eg. PostgreSQL or some NIF lib.

Configuration:

• All reasonable configuration data is taken from environment variables.
• .env file is up to date.
• /docs/ENVIRONMENT.md file is present and describes configuration options, what do they mean. Examples: ael.api, annon.infra. README.md links to it. (Or place everything in README.md).
• LOG_LEVEL env is used.
• ERLANG_COOKIE is accepted at start-time.

Logging:

• Logs are written in JSON format (logger_json).
• Logs does not contain critical data even in DEBUG mode: full dumps of objects that contain it, secrets, tokens, etc. If so - drop log or hide secret from it via Logger configuration (and make sure it's applied).

Security:

• There are no secrets to any service in repository source code. (If not - delete them and tell me to rotate them.)
• There are no secrets that is packed to a container in a CI process. (If not - delete them and tell me to rotate them.)

Debugging in production:

• :release_tools in included in application dependencies.

Template labels

When there is large number of templates, we need a fay to find right one. Simplest case is to label them and query by labels.

• Assign label (string tag) to a template
• Filter templates list by label
• Get list of all existing labels

Rename route POST /templates/:id/print to POST /templates/:id/actions/print

One-click deploy to Heroku

• Investigate one-click deploy for container
• Fallback to Elixir buildpack?

Templates list pagination