Overview

SuiviBourse supports two mutually exclusive configuration modes:

Mode	Source	Best for
Manual	config.yaml	Simple portfolios, static configuration
Events	events/*.csv or events/*.xlsx	Transaction history, multiple brokers, evolving portfolios, historical backfill

The modes are mutually exclusive

Switching to events mode ignores config.yaml entirely. There is no automatic migration between modes.

Mode selection priority

SuiviBourse decides which mode to use in this order:

1. The SB_CONFIG_MODE environment variable (manual or events)
2. The mode field in settings.yaml
3. Auto-detection: events mode if the events source holds at least one .csv or .xlsx file
4. Default: manual

Let auto-detection do the work

Declaring the mode in two places — your deployment and settings.yaml — is the main way the two drift apart. Leave both undeclared and dropping a broker export into events/ is enough to switch to events mode; removing it switches back. An explicit SB_CONFIG_MODE or mode: always wins, so nothing changes for deployments that already state one.

Auto-detection only looks at file extensions, so a README.md or .gitkeep sitting in events/ never triggers it.

Blank counts as unset

An empty SB_CONFIG_MODE (which is what SB_CONFIG_MODE=${SB_CONFIG_MODE} renders to when the variable is missing from a compose .env) is treated as "not set" and falls through to the next rule. The same holds for every SB_* variable: blank means default, never a parse error at boot.

Configuration directory

By default, SuiviBourse looks for its configuration in ~/.config/SuiviBourse/. Inside a container this resolves to /home/appuser/.config/SuiviBourse/.

~/.config/SuiviBourse/
├── config.yaml      # Manual mode
├── settings.yaml    # Events mode selector + options
└── events/          # Events mode transaction files
    ├── 2023.csv
    ├── 2024.csv
    └── broker-export.xlsx

Environment variables

All settings can be overridden with environment variables.

Application

Variable	Default	Description
SB_CONFIG_MODE	(unset)	Force a configuration mode (manual or events). Unset or blank leaves the choice to settings.yaml, then auto-detection, then manual.
SB_REGULAR_INTERVAL	120	Poll interval (seconds) for a symbol whose market is open (REGULAR). Closed markets sleep to the next open instead — see market-aware scraping.
SB_SCRAPING_INTERVAL	(deprecated)	Deprecated heir of the old global scrape interval. Still honored as a fallback for SB_REGULAR_INTERVAL when the latter is unset (logs a warning). Prefer SB_REGULAR_INTERVAL.
SB_PERF_INTERVAL	120	Recompute interval (seconds) for the account_metrics / portfolio_totals performance series (events mode, opt-in accounts).
SB_INGESTION_INTERVAL	300	Event ingestion interval (seconds)
SB_DYNAMIC_EXECUTOR_POOL	false	Auto-size the scheduler's thread pool from the largest same-exchange cohort. Off by default (fixed pool) — opt-in.
SB_EXECUTOR_POOL	10	Fixed thread-pool size when SB_DYNAMIC_EXECUTOR_POOL=false. Ignored (with a warning) when auto sizing is on.
SB_STALENESS_HORIZON	900	Price-freshness sonde: how long (seconds) the stored price must stay frozen across consecutive open-market cycles, while the live quote moves, before a WARNING and the sb_price_staleness gauge fire. 0 disables the sonde. Diagnostic only.
LOG_LEVEL	INFO	Logging level

SB_SCRAPING_INTERVAL is deprecated

The old single scrape interval was renamed to SB_REGULAR_INTERVAL when scraping became per-symbol and market-aware. SB_SCRAPING_INTERVAL is still read as a fallback (with a warning) so existing deployments keep working unchanged, but set SB_REGULAR_INTERVAL going forward. If both are set, SB_REGULAR_INTERVAL wins and SB_SCRAPING_INTERVAL is ignored.

Anti-herd jitter

Each per-symbol job spreads its wake over a hardcoded 30 s jitter window, so a whole exchange's holdings don't fetch in lockstep at market open. This is not an operator dial.

Backfill (events mode)

Variable	Default	Description
SB_BACKFILL_INTERVAL	60	Backfill check interval (seconds)
SB_BACKFILL_DELAY	10	Delay between yfinance requests (seconds)
SB_BACKFILL_CHUNK_DAYS	365	Days of history fetched per request

InfluxDB 3

Variable	Default	Description
INFLUXDB_HOST	http://influxdb:8181	InfluxDB 3 host URL
INFLUXDB_TOKEN	(required)	InfluxDB API token
INFLUXDB_DATABASE	suivi_bourse	InfluxDB database name

Web API

Variable	Default	Description
SB_WEB_PORT	8080	Port for the web API and its /health endpoint

Legacy Prometheus endpoint

Variable	Default	Description
SB_PROMETHEUS_ENABLED	true	Mount the legacy Prometheus /metrics endpoint
SB_METRICS_PORT	8081	Port for the /metrics endpoint

See Legacy Prometheus endpoint for details.