Configuration Reference#

This reference guide covers all configuration options available in the tshistory.cfg configuration file.

Configuration File Locations and Discovery#

Configuration File Search Order

The tshistory configuration system searches for tshistory.cfg in the following order:

  1. Environment Variable Path: $TSHISTORYCFGPATH - if set and file exists

  2. Current Directory: ./tshistory.cfg

  3. Home Directory: ~/tshistory.cfg

  4. XDG Config Directory: $XDG_CONFIG_HOME/tshistory.cfg (defaults to ~/.config/tshistory.cfg)

Environment Variables:

  • TSHISTORYCFGPATH - Override default configuration file path

  • XDG_CONFIG_HOME - XDG base directory specification (defaults to ~/.config)

File Format:

  • INI-style configuration file

  • Case-sensitive section and key names

  • Comments start with #

Required Sections#

[dburi] Section - Database Connections#

The [dburi] section is mandatory and defines database connections for your refinery instances.

Basic Format:

[dburi]
instance_name = database_uri

Supported URI Formats:

  • PostgreSQL: postgresql:///database_name (local connection)

  • PostgreSQL with credentials: postgresql://user:password@host:port/database

  • HTTP API: https://refinery.example.com/api (remote refinery instance)

Examples:

[dburi]
# Local PostgreSQL database
refinery = postgresql:///refinery

# PostgreSQL with full connection details
test_instance = postgresql://user:password@db.company.com:5432/refinery_dev

# Remote refinery instance via HTTP API
external = https://refinery.partner.com/api

# Multiple instances
local = postgresql:///refinery_local
staging = postgresql:///refinery_staging
prod = postgresql:///refinery_prod

API Usage:

  • Default connection: tsa = timeseries() uses the first entry in the [dburi] section

  • Direct URI: tsa = timeseries('postgresql:///mydb') bypasses configuration

Production vs Development:

  • Production deployments typically use a single database URI

  • Multiple entries are primarily useful for developers and testers who need to work with different environments

  • The first entry serves as the default when no specific instance is requested

Optional Sections#

[sources] Section - Data Mesh Configuration#

The [sources] section configures external refinery instances for data mesh setups, allowing your refinery to consume data from other refineries.

Format:

[sources]
local_instance.source_name = remote_uri, namespace

Parameters:

  • local_instance - Must match a name from the [dburi] section

  • source_name - Local alias for the remote source

  • remote_uri - HTTP API endpoint of the remote refinery

  • namespace - Always use tsh for refinery sources

Examples:

[sources]
# Connect to external weather data
refinery.meteo = https://refinery.meteo.company.com/api, tsh

# Multiple external sources
refinery.weather = https://refinery.weather.partner.com/api, tsh
refinery.market = https://refinery.market.partner.com/api, tsh

Usage:

  • External series become available as if they were local

  • Transparent access through normal API calls

  • Requires proper authentication (see [auth] section)

[auth] Section - Authentication for External Sources#

The [auth] section provides authentication credentials for accessing external refinery instances defined in the [sources] section.

Authentication Methods:

HTTP Basic Authentication:

[auth]
source_name.uri = https://external.refinery.com/api
source_name.login = username
source_name.password = password

OpenID Connect - Client Credentials (M2M):

[auth]
source_name.uri = https://external.refinery.com/api
source_name.client_id = your_client_id
source_name.client_secret = your_client_secret
source_name.domain = openid.provider.com/realms/realm_name

OpenID Connect - PKCE (Public Client):

[auth]
source_name.uri = https://external.refinery.com/api
source_name.pkce =
source_name.client_id = public_client_id
source_name.domain = openid.provider.com/realms/realm_name

Real-World Examples:

[auth]
# Basic authentication
meteo.uri = https://refinery.meteo.pythonian.fr/api
meteo.login = username
meteo.password = password

# Machine-to-Machine OAuth
partner_api.uri = https://refinery.partner.pythonian.fr/api
partner_api.client_id = partner_client
partner_api.client_secret = your_client_secret
partner_api.domain = openid.pythonian.space/realms/pythonian

# PKCE flow (public client)
public_api.uri = https://refinery.public.pythonian.fr/api
public_api.pkce =
public_api.client_id = public-client
public_api.domain = openid.pythonian.space/realms/pythonian

Key Points:

  • Authentication is required for most external refinery instances

  • Basic auth is simpler but less secure than OpenID Connect

  • PKCE flow is for public clients (no client secret)

  • M2M (client credentials) flow is for server-to-server communication

  • [auth] entries must correspond to sources defined in [sources] or [dburi]

  • [auth] is for authenticating as a client to external services

[server-auth] Section - Server Authentication Configuration#

The [server-auth] section configures authentication for the refinery server itself (when acting as a server rather than client).

Format:

[server-auth]
client_id = your_server_client_id
client_secret = your_server_client_secret
domain = openid.provider.com/realms/realm_name
authorize_uri = https://your.refinery.com/authorize
audience = https://your.refinery.com/api

Usage:

  • Used when your refinery instance needs to authenticate incoming requests

  • Configures your refinery instance as an OAuth2 server

  • Used when other clients need to authenticate to access your refinery

  • Different from [auth] which is for authenticating to external services

Note

For detailed server authentication setup, see the Securing the Refinery chapter.

[dashboard] Section - External Dashboard URL Configuration#

The [dashboard] section defines URLs for external dashboard services and integrations.

Important Note:

  • This section is only for external dashboard services

  • The built-in dashboard (available at http://your-refinery/dashboards) requires no configuration

  • Most installations do not need this section

Format:

[dashboard]
refinery = external_dashboard_url
dashboards = external_dashboards_service_url

Examples:

[dashboard]
# External dashboard service for the refinery instance
refinery = http://external-dashboard.company.com

# Dedicated external dashboards service
dashboards = http://external-dashboards.company.com/dashboards/

Usage:

  • Configures integration with external dashboard services (not the built-in one)

  • Used by the refinery web interface to link to external dashboard systems

  • Allows for integration with third-party dashboard platforms

Key Points:

  • Optional section - only needed if integrating with external dashboard services

  • The built-in dashboard system requires no configuration entries

  • URLs should point to accessible external dashboard service endpoints

Examples and Use Cases#

Basic Single Instance Setup#

The minimal configuration for a local development setup:

[dburi]
refinery = postgresql:///refinery

This configuration:

  • Uses local PostgreSQL database named “refinery”

  • No external sources or authentication

  • Built-in dashboard available at http://localhost:5000/dashboards

Multi-Database Development Setup#

Configuration for developers working with multiple environments:

[dburi]
local = postgresql:///refinery_local
staging = postgresql:///refinery_staging
prod = postgresql:///refinery_prod

Usage:

  • tsa = timeseries() connects to local (first entry)

  • tsa = timeseries('postgresql:///refinery_staging') connects to staging

  • Useful for testing migrations and data comparisons

Data Mesh Configuration with Client Authentication#

Production setup consuming data from external refinery instances:

[dburi]
company = postgresql://user:password@db.company.com:5432/refinery

[sources]
company.weather = https://refinery.weather.partner.com/api, tsh
company.market = https://refinery.market.partner.com/api, tsh

[auth]
# Authentication for weather source (matches [sources] entry)
weather.uri = https://refinery.weather.partner.com/api
weather.login = your_username
weather.password = your_password

# Authentication for market source (matches [sources] entry)
market.uri = https://refinery.market.partner.com/api
market.client_id = your_client_id
market.client_secret = your_client_secret
market.domain = auth.market.partner.com/realms/api

Key Point:

  • [auth] entries must correspond to sources defined in [sources] or [dburi]

  • [auth] is for authenticating as a client to external services

Enterprise Server Authentication Configuration#

Configuration for when your refinery acts as a server requiring authentication:

[dburi]
production = postgresql://user:password@db.internal:5432/refinery_prod

[server-auth]
client_id = your_server_client_id
client_secret = your_server_client_secret
domain = openid.yourprovider.com/realms/your_realm
authorize_uri = https://your.refinery.com/authorize
audience = https://your.refinery.com/api

Key Points:

  • [server-auth] configures your refinery instance as an OAuth2 server

  • Used when other clients need to authenticate to access your refinery

  • Different from [auth] which is for authenticating to external services

  • Requires OpenID Connect provider configuration