Configuration Templates

Ninja uses Tera templates to generate service configuration files.

Template System

Files Involved

.ninja/options.toml - User-editable values
.ninja/config.tmpl - Tera template
Output file - Path from manifest.toml

Workflow

# 1. Edit options
nano ~/.ninja/shurikens/{name}/.ninja/options.toml

# 2. Generate configuration
shurikenctl configure {name}

# 3. Configuration written to specified path

Template Syntax

Basic Variables

[server]
host = {{ host }}
port = {{ port }}
debug = {{ debug }}

Defaults

[server]
host = {{ host | default(value="127.0.0.1") }}
port = {{ port | default(value=8080) }}

Conditionals

{% if enable_ssl %}
[ssl]
cert = {{ ssl_cert }}
key = {{ ssl_key }}
{% endif %}

Loops

{% for worker in workers %}
[[workers]]
id = {{ worker.id }}
threads = {{ worker.threads }}
{% endfor %}

Injected Variables

Ninja automatically provides:

{{ platform }} - Current OS: linux, windows, or macos
{{ root }} - Absolute path to shuriken directory

Example Usage

[paths]
data = {{ root }}/data
logs = {{ root }}/logs
config = {{ root }}/config

[system]
platform = {{ platform }}

Options File Format

.ninja/options.toml:

# Server settings
host = "localhost"
port = 8080
debug = false

# SSL settings
enable_ssl = true
ssl_cert = "/etc/ssl/cert.pem"
ssl_key = "/etc/ssl/key.pem"

# Workers
[[workers]]
id = 1
threads = 4

[[workers]]
id = 2
threads = 4

Complete Example

Template (`.ninja/config.tmpl`)

[server]
bind = {{ bind_address | default(value="0.0.0.0") }}:{{ port }}
workers = {{ worker_count | default(value=4) }}
log_level = {{ log_level | default(value="info") }}

[paths]
static = {{ root }}/static
data = {{ root }}/data
logs = {{ root }}/logs

{% if enable_tls %}
[tls]
cert = {{ tls_cert }}
key = {{ tls_key }}
{% endif %}

[system]
platform = {{ platform }}

Options (`.ninja/options.toml`)

bind_address = "127.0.0.1"
port = 8080
worker_count = 8
log_level = "debug"

enable_tls = true
tls_cert = "/etc/ssl/cert.pem"
tls_key = "/etc/ssl/key.pem"

Generated Output

[server]
bind = 127.0.0.1:8080
workers = 8
log_level = debug

[paths]
static = /home/user/.ninja/shurikens/myapp/static
data = /home/user/.ninja/shurikens/myapp/data
logs = /home/user/.ninja/shurikens/myapp/logs

[tls]
cert = /etc/ssl/cert.pem
key = /etc/ssl/key.pem

[system]
platform = linux

Manifest Configuration

Specify template and output in manifest.toml:

[config]
config-path = "server.conf"

Template is always .ninja/config.tmpl.

Best Practices

Provide defaults - Use | default(value=...) for optional values
Use {{ root }} - Makes paths portable across installations
Keep logic simple - Complex generation belongs in management scripts
Document options - Add comments in options.toml template
Test templates - Run configure to verify output

Debugging

Check template syntax:

# Template is at
~/.ninja/shurikens/{name}/.ninja/config.tmpl

Verify options:

# Options file
~/.ninja/shurikens/{name}/.ninja/options.toml

Review output:

# Generated config location from manifest
cat ~/.ninja/shurikens/{name}/{config-path}

Configuration Templates

On this page