Docker Container | docxtemplater

Docker HTTP API

The docker API allows you to run all docxtemplater modules contained in the ENTREPRISE plan, without having to configure them. The modules are already configured to good defaults and work well with each other.

The API exposes an HTTP POST route to do the generation that takes as input the template file and the data to be used for the generation.

The API outputs the generated file.

The docker image can be used to generate documents from other languages (Java, .Net, Ruby, Golang, …), since it only requires to do one HTTP Call.

Usage with curl

This example requires you to have input.docx, data.json and it exports output.docx

# creates a new file descriptor 3 that redirects to 1 (STDOUT)
exec 3>"output.docx"

# Run curl in a separate command,
# capturing output of -w "%{http_code}" into HTTP_STATUS
# and sending the content to this command's STDOUT with -o >(cat >&3)

curl --silent \
   -X POST \
   -F "data=@data.json" \
   -F "filecomment=This is an image file" \
   -F "doc=@input.docx" \
   -w "%{http_code}" \
   "$host/api/v1/generate" \
   -o >(cat >&3) >/tmp/httpstatus || code="$?"

Configuration

It is possible to configure your instance by editing the configuration.js file.

There are different parts that you can configure.

By implementing configureAngularParser, you can add angular filters that you want to be able to use in your template :

configureAngularParser(expressions) {
    /* Here you can define custom filters
     * For example if you wish to write { clientName | upper }
     */

    expressions.filters.upper = function(input) {
        // This condition should be used to make sure that if your input is undefined, your output will be undefined as well and will not throw an error

        if(!input)
            return input;
        return input.toUpperCase();
    }
    return expressions;
},

By implementing configureDocxtemplater, you can attach additional modules that you have developped yourself.

configureDocxtemplater(doc) {
    /*
     * Here you can configure the docxtemplater instance before compiling/rendering
     * For example :
     *
     * doc.attachModule(new MyCustomModule());
     */
    return doc;
},

By implementing configureModule, you can modify the configuration of a given module.

configureModule(moduleName, options) {
    /*
     * Here you can configure each of the docxtemplater modules
     * For example to fetch urls for the image module :
     */

    const https = require("https");
    const http = require("http");
    const Stream = require("stream").Transform;

    if (moduleName === "image") {
       options.getImage = function (url) {
           return new Promise(function (resolve, reject) {
               (url.substr(0, 5) === "https" ? https : http)
               .request(url, function (response) {
                   if (response.statusCode !== 200) {
                       return reject(
                           new Error(
                               `Request to ${url} failed, status code: ${response.statusCode}`
                           )
                       );
                   }
                   const data = new Stream();
                   response.on("data", function (chunk) {
                       data.push(chunk);
                   });
                   response.on("end", function () {
                       resolve(data.read());
                   });
                   response.on("error", function (e) {
                       reject(e);
                   });
               })
               .end();
           });
       };
    }

    return options;
}

Specs to host the docker image

You can host the docker image on an EC2 Amazon instance for example, or on a virtual machine that you own.

Recommended specs would be :

A decent CPU, the docker image uses only one core (no parallelism in docxtemplater), so you don't "need" a 16 CPU server. (But you can have one instance of the docker image for each CPU if you expect very high load). Docxtemplater is CPU bound, meaning that it is there that speed improvements can be made mostly.
2GB of Ram or more for each instance of the docker image
SSD and good network quality cannot hurt as well.

CHANGELOG

3.13.0

Use async data generation and make it possible to configure a single module (for example the image module)
Update table-module-3.13.7
Update slides-module-3.3.5
Update image-module-3.8.13
Update html-module-3.26.9
Update error-location-module-3.2.5
Update docxtemplater to 3.25.0
Update chart-module-3.1.0