rsubst

rsubst is a simple templating CLI tool built in Rust, leveraging MiniJinja to provide dynamic substitutions and conditional logic in configuration files and other text-based templates. It serves as a flexible and powerful alternative to simpler tools like envsubst.

Motivation

rsubst was created to simplify Docker container configuration at runtime. Previously, tools like envsubst were easy to use but lacked support for conditionals and robust escaping, whereas solutions like Jinja2 provided advanced templating but required an additional Python runtime inside containers. rsubst combines the simplicity of envsubst with powerful conditional logic from Jinja-style templating, packaged in a lightweight Rust binary that eliminates external dependencies.

Features

• Environment variable substitution
• Conditional logic (if, else, elif)
• Looping constructs (for loops)
• Access to built-in filters
• Lightweight and fast execution
• Built with Rust for efficiency and reliability

Installation

To install rsubst, ensure you have Rust installed and use Cargo:

cargo install rsubst

Build for release with musl libc on Linux:

rustup target add x86_64-unknown-linux-musl
cargo build --release --target x86_64-unknown-linux-musl

You can use cargo-zigbuild on other platforms.

Usage

Basic usage:

rsubst output.conf.j2 > output.conf

With environment variables:

export APP_ENV=production
rsubst output.conf.j2 > output.conf

Examples

Simple Variable Substitution

Given a template file config.conf.j2:

app_environment={{ APP_ENV }}

Set an environment variable and render the template:

export APP_ENV=staging
rsubst config.conf.j2

Output:

app_environment=staging

Conditional Logic

Template example (config.conf.j2):

{% if APP_ENV == "production" %}
debug_mode=false
{% else %}
debug_mode=true
{% endif %}

Usage:

export APP_ENV=production
rsubst config.conf.j2

Output:

debug_mode=false

Loop Example

Template (servers.yaml.j2):

servers:
{% for server in SERVERS | split(",") -%}
  - {{ server }}
{% endfor %}

Usage:

export SERVERS="web01,web02,db01"
rsubst servers.yaml.j2

Output:

servers:
  - web01
  - web02
  - db01

License

rsubst is available under the MIT license. See LICENSE file for more details.