Configuration

The TestBench Requirement Service is configured through a single TOML file (default: config.toml in the install directory). This page documents every available option.

tip

Use the CLI wizards instead of editing the file by hand. They validate your input and prevent syntax errors:

testbench-requirement-service init              # Create a new config from scratch
testbench-requirement-service configure         # Update an existing config
testbench-requirement-service set-credentials   # Update credentials only

See CLI Commands for all options.

---

Configuration precedence

The following order shows which source takes precedence when the same setting is defined in multiple places (highest priority first):

1. Command-line flags (start --host ... --port ...)
2. Environment variables
3. config.toml
4. Built-in defaults

---

Full example

This example uses the JSONL reader. Adjust reader_class and [testbench-requirement-service.reader_config] for other readers.

# config.toml
[testbench-requirement-service]
reader_class = "JsonlRequirementReader"
host = "127.0.0.1"
port = 8020
password_hash = "your_generated_hash"
salt = "your_generated_salt"

# Server process settings
[testbench-requirement-service.server]
single_process = true

# Console logging
[testbench-requirement-service.logging.console]
log_level = "INFO"
log_format = "%(asctime)s %(levelname)8s: %(message)s"

# File logging
[testbench-requirement-service.logging.file]
log_level = "INFO"
log_format = "%(asctime)s - %(levelname)8s - %(name)s - %(message)s"
file_path = "testbench-requirement-service.log"

# JSONL reader configuration (inline, recommended)
[testbench-requirement-service.reader_config]
requirements_path = "requirements/jsonl/"

---

Service settings

[testbench-requirement-service]

Reader

Option	Type	Description	Default
reader_class	String	Identifies the reader to load. See supported formats below.	"JsonlRequirementReader"
reader_config_path	String	Path to a separate reader config file (.toml or .properties). When omitted, the [testbench-requirement-service.reader_config] section of the main config file is used.	—

Example:

# config.toml
[testbench-requirement-service]
reader_class = "JsonlRequirementReader"
reader_config_path = "jsonl_config.toml"
...

reader_class formats

Format	Example	Notes
Built-in class name	"JsonlRequirementReader"	Short name of any class in the built-in testbench_requirement_service.readers package
File path with extension	"custom_reader.py"	Absolute path, or relative to the directory the service is started from
File path without extension	"custom_reader"	.py is appended automatically
Module string	"my_package.MyReader"	Imported via importlib; the file must be on PYTHONPATH or in the working directory
Full dotted module path	"my_package.my_module.MyReader"	Module and class can also be combined into one string

reader_config_path formats

Supported file types:

• .toml — Either raw key-value pairs at the top level, or a full service config file — the [testbench-requirement-service.reader_config] section is extracted automatically.
• .properties — Java-style key=value pairs (same format as used by the Excel and Jira readers).

The path is resolved relative to the directory where the service is started.

Server

Option	Type	Description	Default
host	String	Host address to bind to.	"127.0.0.1"
port	Integer	Port number to listen on.	8020
debug	Boolean	Enable debug mode (verbose logging, auto-reload). Do not use in production.	false

Example:

# config.toml
[testbench-requirement-service]
host = "127.0.0.1"
port = 8020
debug = false
...

Authentication

Option	Type	Description	Default
password_hash	String	Hashed service password (generated by set-credentials).	—
salt	String	Salt used for password hashing (generated by set-credentials).	—

Example:

# config.toml
[testbench-requirement-service]
password_hash = "your_generated_hash"
salt = "your_generated_salt"
...

All API endpoints (except Swagger UI) require HTTP Basic Authentication.

Setting credentials

Generate and store a password hash and salt in your config:

testbench-requirement-service set-credentials

You will be prompted for a username and password. The command writes password_hash and salt into config.toml.

Non-interactive mode (e.g. for scripts or CI pipelines — avoid passing --password directly in a shared-environment shell to prevent it from being written to shell history):

testbench-requirement-service set-credentials --username ADMIN_USERNAME --password PASSWORD

HTTPS / TLS

Option	Type	Description	Default
ssl_cert	String	Path to the certificate file.	—
ssl_key	String	Path to the private key file.	—
ssl_ca_cert	String	Path to the CA certificate. When set, client certificates are required (mTLS).	—

Example:

# config.toml
[testbench-requirement-service]
ssl_cert = "certs/server.crt"
ssl_key = "certs/server.key"
ssl_ca_cert = "certs/ca.crt"   # optional — enables mTLS
...

Set both ssl_cert and ssl_key to enable HTTPS. Add ssl_ca_cert to require client certificates (mTLS).

limitation

When using mTLS (ssl_ca_cert), the service runs in single-process mode.

Reverse proxy

Only needed when the service runs behind a load balancer or reverse proxy (e.g., Nginx).

Option	Type	Description	Default
proxies_count	Integer	Number of proxy layers (for X-Forwarded-For depth)	—
real_ip_header	String	Custom header for client IP (e.g. "X-Real-IP")	—
forwarded_secret	String	Secret token for RFC 7239 Forwarded header validation	—

Example:

# config.toml
[testbench-requirement-service]
proxies_count = 1
real_ip_header = "X-Real-IP"
forwarded_secret = "secret"
...

Header priority (when multiple options are configured):

1. Forwarded header (only if forwarded_secret is set and the secret matches)
2. Custom header from real_ip_header
3. X-Forwarded-For + other X-Forwarded-* headers (if proxies_count is set)
4. Direct connection IP (default)

Security

Without proxy configuration, the service ignores all proxy headers. This is safe. Only enable proxy settings when actually behind a proxy.

Nginx example

Nginx configuration:

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /path/to/certificate.crt;
    ssl_certificate_key /path/to/private.key;

    location / {
        proxy_pass http://127.0.0.1:8020;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Service configuration:

# config.toml
[testbench-requirement-service]
host = "127.0.0.1"   # bind to localhost only
port = 8020
proxies_count = 1     # trust one proxy layer

For maximum security with the RFC 7239 Forwarded header, add to Nginx:

proxy_set_header Forwarded "for=$remote_addr;proto=$scheme;secret=your-token";

And in config.toml:

forwarded_secret = "your-token"

---

Server process settings

[testbench-requirement-service.server]

Controls how Sanic spawns and manages its worker process. In most cases you can leave out this section and rely on the defaults.

Option	Type	Description	Default
single_process	Boolean	Run in single-process mode. Required when using mTLS. Set to false to enable multi-worker throughput.	true
keep_alive_timeout	Integer	Seconds an idle HTTP keep-alive connection is held open waiting for the next request before being closed. A shorter value reduces the number of open connections that can delay shutdown.	5
run_kwargs	Table	Raw keyword arguments forwarded verbatim to Sanic's run() call. Use for advanced Sanic tuning not exposed by other settings.	{}

Example:

# config.toml
[testbench-requirement-service.server]
single_process = false
keep_alive_timeout = 3
run_kwargs = { workers = 4 }

---

Logging

Console

[testbench-requirement-service.logging.console]

Option	Type	Description	Default
log_level	String	Minimum log level. One of DEBUG, INFO, WARNING, ERROR, CRITICAL.	"INFO"
log_format	String	Python logging format string.	"%(asctime)s %(levelname)8s: %(message)s"

Example:

# config.toml
[testbench-requirement-service.logging.console]
log_level = "INFO"
log_format = "%(asctime)s %(levelname)8s: %(message)s"

File

[testbench-requirement-service.logging.file]

Option	Type	Description	Default
log_level	String	Minimum log level. One of DEBUG, INFO, WARNING, ERROR, CRITICAL.	"INFO"
log_format	String	Python logging format string.	"%(asctime)s - %(levelname)8s - %(name)s - %(message)s"
file_path	String	Path to the log file. Relative paths are resolved from the working directory.	"testbench-requirement-service.log"

Example:

# config.toml
[testbench-requirement-service.logging.file]
log_level = "INFO"
log_format = "%(asctime)s - %(levelname)8s - %(name)s - %(message)s"
file_path = "testbench-requirement-service.log"

---

Reader configuration

Each reader has its own configuration ([testbench-requirement-service.reader_config] section or as separate configuration file). See the individual reader documentation for the full option reference:

• JSONL Reader configuration
• Excel Reader configuration
• Jira Reader configuration

---

Running multiple instances

Each start command loads exactly one config file and binds to one port. To serve multiple data sources simultaneously — for example, one service for Excel requirements and one for Jira — start one process per config file on a different port.

Setup

1. Create one config file per instance:

excel_config.toml

# excel_config.toml
[testbench-requirement-service]
reader_class = "ExcelRequirementReader"
port = 8020

[testbench-requirement-service.reader_config]
# Excel-specific settings ...

jira_config.toml

# jira_config.toml
[testbench-requirement-service]
reader_class = "JiraRequirementReader"
port = 8021

[testbench-requirement-service.reader_config]
# Jira-specific settings ...

2. Start each instance in its own terminal (or as separate Windows services):

# Terminal 1 — Excel service on port 8020
testbench-requirement-service start --config excel_config.toml

# Terminal 2 — Jira service on port 8021
testbench-requirement-service start --config jira_config.toml

The --port flag overrides the port in the config file, so you can also reuse the same config and just change the port at start time:

testbench-requirement-service start --config shared_config.toml --port 8022

TestBench integration with multiple instances

For each running instance, configure a separate RMProxy wrapper entry in TestBench pointing to the corresponding URL:

# Excel service
server.url=http://127.0.0.1:8020

# Jira service
server.url=http://127.0.0.1:8021

See the TestBench Integration page for the full RMProxy setup.

Running as Windows services

When running multiple instances as Windows services, give each service a distinct name and point it to its own config file. See the Windows Service Installation guide for details.