Straw

Straw is an HTTP based engine for rendering Liquid templates from different sources (Git, filesystem, database).

• Getting Started
• Architecture
  • Sources
    • Git
    • Filesystem
    • Database
    • Inline
  • Environments
    • Syncing
    • Global Variables
    • Engine
  • Rendering

Getting Started

Docker

You can run Straw as a Docker container.

First, you need to write a straw.yaml where you define your sources and environments. Example:

sources:
  - name: straw
    git:
      repoUrl: https://github.com/moritzrinow/straw
      clonePath: /tmp/repos/straw
      branch: master
      root: examples/sources/hello
      include:
        - "*.liquid"
environments:
  - name: test
    source: straw
    sync: 1m

Run the container:

docker run -v ./straw.yaml:/etc/straw/straw.yaml -p 8080:8080 ghcr.io/moritzrinow/straw

Your first render request:

POST http://localhost:8080/render
Content-Type: application/json

{
    "environment": "test",
    "template": "hello",
    "data": {
        "name": "Your Name"
    }
}

You should see the following response:

Hello Your Name!

Architecture

Sources

A source defines where and how templates are fetched. They can be described as a simple function that returns a set of templates (name, content). There is support for different types of sources.

A full reference of the sources configuration can be found here.

Git

A source of type git reads templates from a remote Git repository, allowing you to target specific branches, tags and commits. In case the repository is private, you may specify additional authentication properties.

Example configuration (public repository):

sources:
  - name: git_example
    git:
      repoUrl: https://github.com/moritzrinow/straw
      clonePath: /tmp/repos/straw
      root: examples/sources/test
      tag: v0.1.0
      include:
        - "*.liquid"

Example configuration (private repository):

sources:
  - name: git_example
    git:
      repoUrl: https://github.com/moritzrinow/straw
      clonePath: /tmp/repos/straw
      root: examples/sources/test
      tag: v0.1.0
      include:
        - "*.liquid"
      sshKey: |
        -----BEGIN RSA PRIVATE KEY-----
        MIIBOgIBAAJBAKj34GkxFhD90vcNLYLInFEX6Ppy1tPf9Cnzj4p4WGeKLs1Pt8Qu
        ...
      username: user
      password: password
      token: token

Filesystem

A source of type fs reads templates from a directory in the host filesystem.

Example configuration:

sources:
  - name: fs_example
    fs:
      root: /var/opt/templates
      include:
        - "*.liquid"

Database

A source of type db reads templates from a database supporting SQL.

The following drivers are supported:

• postgres (PostgreSQL)
• mysql (MySQL)
• sqlite3 (SQLite)

Example configuration:

sources:
  - name: db_example
    db:
      driver: postgres
      connection: host=localhost port=5432 dbname=example user=postgres password=password sslmode=disable
      query: |
        SELECT name, content FROM templates;

The query may be arbitrary as long as the result set returns rows with two columns of type string. The first column represents the template name/path, the second on it's content. For example, you can also make use of WHERE and ORDER BY clauses.

Inline

A source of type inline reads templates directly from the YAML config.

Example configuration:

sources:
  - name: inline
    inline:
      hello.liquid: |
        Hello {{ name }}!

Environments

An environment defines an isolated rendering environment for templates. The set of templates available in the environment is determined by the source it references. One source may be referenced by multiple environments.

Example environment configuration:

environments:
  - name: test
    source: git_example

Syncing

The process of loading templates from a source and compiling them in the environment is called syncing. Every environment is initially synced once with its source at startup. You can optionally configure an environment to be synced periodically.

Example configuration where sync happens every 10 minutes:

environments:
  - name: test
    source: git_example
    sync: 10m

Global Variables

You can configure an environment to have global variables set for every template.

environments:
  - name: test
    source: git_example
    sync: 10m
    globals:
      name: John Doe

When rendering Hello {{ name}}! in this environment, it would yield Hello John Doe!.

Engine

Every environment has its own rendering engine instance. Straw supports the choice of two engines:

• osteele (recommended, default, source)
• notifuse (experimental, source)

Example configuration:

environments:
  - name: test
    source: git_example
    engine: osteele

Rendering

Since Straw is an HTTP service, rendering templates is available via HTTP endpoints.

Rendering a single template:

POST /render
Content-Type: application/json

{
    "environment": "test",
    "template": "hello",
    "data": {
        "name": "John Doe"
    }
}

In case of success, the rendered template will be returned in the request body as text/plain.

You can also batch render:

POST /render/batch
Content-Type: application/json

{
    "requests": [
        {
            "environment": "test",
            "template": "hello",
            "data": {
                "name": "John Doe"
            }
        },
        {
            "environment": "test",
            "template": "hello",
            "data": {
                "name": "Jane Doe"
            }
        }
    ]
}

When batch rendering, the results are returned as multipart/mixed content, where every part contains the rendered template with Content-Type: text/plain in case of success, or an error object with Content-Type: application/json in cas of an error.