- specify a time limit per request (seconds)
Environment Variables:
The `-r`, `-s3` or `-github` arguments (mutually exclusive) allow you to specify a repository (`-r` is a local directory, `-s3` is an S3 URL and `-github` is a GitHub repository) that will be used to store DataTemplates on the server via the "Get Link" and "Update Link" buttons. The generated link is guaranteed to be unique and a different link will be created every time.
If you use an S3 bucket then you will also need to provide some credentials (and the region) via the "S3_" environment variables, which has read and write permissions to the S3 bucket. It supports both AWS S3 as well as Generic S3 via the following URL formats (https is assumed):
- AWS S3 - `.s3..amazonaws.com`
The `-rl` argument is used to provide an optional rate limit of the source IP - the "rate" is how many requests are permitted and the "limit" is the interval in which those requests are permitted - it can be specified in "s", "m" or "h" (e.g. "5/30s", "10/1m" or "30/1h"). This is currently only applied to "Get Link" and Web Log authentication.
The `-weblog` argument in combination with the `JFX_WEBLOG_KEY` environment variable enables the Web Log interface to view the current application logs - this can be accessed from a web browser using the URL `/logs` - the user will be prompted for the key or they can provide it via a query string of `?key=`.
If you specify `-allowjs` then this allows you to inject dynamic JavaScript into HTML outputs and JinjaFx Input modals, but this basically disables the scripting aspects of the Content Security Policy (use `-nocsp` to disable it completely), which protects you from XSS attacks. This is only advisable if you are hosting this internally and you trust your users.
The preferred method of running the JinjaFx Server is with HAProxy in front of it as it supports TLS termination as well as HTTP/2 and HTTP/3 transports (QUIC). In addition to running it via systemd, you can also run it as a container using Docker, Podman or Kubernetes (the `Dockerfile` is within the [contrib](/contrib) directory). The container image will always be available at https://hub.docker.com/repository/docker/cmason3/jinjafx_server - the latest tag will always refer to the latest released version, although it is recommended to use explicit version tags.
For health checking purposes, if you perform a GET request to `/ping` then you should get an "OK" response if the JinaFx Server is up and working (these requests are omitted from the logs).
### Shortcut Keys
As well as supporting the standard CodeMirror shortcut keys for the "data.csv", "global.yml", "vars.yml" and "template.j2" panes, it also supports the following custom shortcut keys:
- F11 / Cmd-Enter - Toggle Fullscreen
- Ctrl-G / Cmd-G - Generate
- Ctrl-S / Cmd-S - Update Link
- Ctrl-F / Cmd-F - Find
### DataSets
The DataSet feature allows you to include multiple different "data.csv" and "vars.yml" contents while maintaining the same "template.j2". When enabled it also enables a "global.yml" pane for specifying global variables which are common across all DataSets (any variables which are redefined in "vars.yml" will overwrite variables in "global.yml"). This is to support scenarios where you have different DataSets for your Live vs your Test environments, but the template should be the same. There are no limits on the number of different DataSets that can be added to a single DataTemplate (the name must start with a letter and only contain alphanumerical, "-", " " or "_" characters). When you click "Generate" it will use the currently active DataSet to generate the output - clicking on the name of the current DataSet (by default there is a single "Default" DataSet) allows you to switch between the different DataSets.
You can also select a specific DataSet when you load a DataTemplate using the `ds` query string parameter (i.e. `?ds='`) or by adding an additional path element (i.e. `/dt/
/`). When using DataTemplates and DataSets you can also specify `?g` as a query string parameter to trigger automatic generation - this only works if you allow popups or you implement a JinjaFx Input modal.
### Output Formats
JinjaFx Server supports the ability to use "output" tags to create different outputs with different names like JinjaFx, but it also allows you to optionally specify how you want the output to be rendered. By default, the output is rendered as "text" but you also have the option to specify "html" and "markdown" (for GitHub Flavoured Markdown), which will result in the output being rendered appropriately, e.g:
```jinja2
...
- Item 1
```
GitHub Flavoured Markdown doesn't support the use of HTML tags, but JinjaFx allows custom tags within Markdown, which allows you to change the colour of your text (i.e. `{red}Red Text{/red}`). The supported tags are as follows: 'red', 'green', 'blue' and 'highlight'. You can also paste in an image and it will convert it to a Base64 encoded Data URI that is formatted as Markdown.
### Ansible Vault
JinjaFx Server supports the ability to perform Ansible Vault encryption of strings from within the browser using client side JavaScript. By clicking on the padlock it will prompt you for your string and the password to use which you can then use within `vars.yml`. JinjaFx doesn't support the ability to use different passwords for different strings within the same DataTemplate so it is important that all vaulted strings are using the same password within the same DataTemplate.
By default JinjaFx will fail with "invalid ansible vault password" if the provided Ansible Vault password is empty or missing. The `jinjafx_vault_undefined` variable allows you to change this behaviour - if set to `True` then it will proceed to process the template, but if it can't decrypt a vaulted variable due to a missing password then the variable won't be defined.
### JinjaFx Input
There might be some situations where you want inputs to be provided during the generation of the template which are not known beforehand. JinjaFx supports the ability to prompt the user for input using the `jinjafx_input` variable which can be specified in `vars.yml`. The following example demonstrates how we can prompt the user for two inputs ("Name" and "Age") before the template is generated:
```yaml
These inputs can then be referenced in your template using `{{ jinjafx_input.name }}` or `{{ jinjafx_input['age'] }}` - the variable name is the field name and the prompt text is the value. However, there might be some situations where you want a certain pattern to be followed or where an input is mandatory, and this is where the advanced syntax comes into play (you can mix and match syntax for different fields):
```yaml
Under the field the `text` key is always mandatory, but the following optional keys are also valid:
- `required` - can be True or False (default is False)
- `pattern` - a regular expression that the input value must match
- `type` - if set to "password" then echo is turned off - used for inputting sensitive values
In addition to the above prompt syntax, we also support the ability to specify a custom html input form to provide greater flexibility. As JinjaFx is built on Bootstrap 5, it uses the Bootstrap 5 Modal syntax to specify what is contained in the body of your modal form. Bootstrap works on a row and column grid with each row comprising of 12 columns - you use the various "col-n" classes to specify how wide each element is.
You can specify a custom input form using the `body` variable under `jinjafx_input` within your "vars.yml" - if this exists then whatever you have in `prompt` is ignored.
```yaml
If you pass `-allowjs` (or `-nocsp`) on the command line then you can also specify a `script` section, which allows you to perform dynamic actions within your modal, e.g:
```yaml
Within the script block, you can also use `jinjafx.rows` and `jinjafx.data()`, which have identical syntax to the Jinja2 versions and allows you to access `data.csv` from within a JinjaFx Input modal. Similarly you can use `jinjafx.outputs` within script blocks of HTML outputs to access all the rendered outputs.
You can also specify an optional `size` attribute alongside the `body` attribute which sets the width of the modal using the pre-defined Bootstrap sizes (i.e. "sm", "lg" and "xl"). The input form supports full native HTML validation using `required` and `pattern` attributes. The values which are input are then mapped to Jinja2 variables using the `data-var` custom attribute (e.g. `data-var="name"` would map to `jinjafx_input['name']` or `jinjafx_input.name`):
```jinja2
If you specify the same `data-var` value more than once in the input form then the variable will be converted into a list using the values in the order they appear in the form.
](https://jinjafx.io)