Configuration¶

The monitor reads its configuration from environment variables at startup and checks them first. If a value is invalid, the monitor does not start and names the variable at fault.

Required¶

ISCC_MONITOR_DB

Path to the SQLite database file of the network, for example /data/monitor.db. The monitor creates the file on the first start. Use one file per network. Never point two running instances at the same file.

ISCC_MONITOR_REALM

The source of the network's hubs: the URL or file path of an iscc-hub Hub-List.

Network	Hub-List URL
Mainnet	`https://raw.githubusercontent.com/iscc/iscc-hub/refs/heads/main/hubs/mainnet.yaml`
Testnet	`https://raw.githubusercontent.com/iscc/iscc-hub/refs/heads/main/hubs/testnet.yaml`

The monitor fetches a URL again every hour, so changed hub entries apply without a restart. A newly added hub is followed after a restart. The image default is a built-in testnet list whose hosts no longer serve, so always set this variable.

Timing¶

Intervals use Go's duration syntax, such as 30s, 5m or 1h, and must be positive.

Variable	Default	Meaning
`ISCC_MONITOR_NORMAL`	`5m`	Poll interval for each hub
`ISCC_MONITOR_FROZEN`	`1h`	Poll interval for a frozen hub, for evidence. Must be at least `ISCC_MONITOR_NORMAL`
`ISCC_MONITOR_OTS_INTERVAL`	`1h`	Interval for sending new roots to the OpenTimestamps calendar and checking pending roots for Bitcoin confirmation

The OpenTimestamps pass also runs once at startup. However short the interval, the monitor asks the calendar about one root at most once an hour. While the root stays unconfirmed, the wait doubles, up to once a day.

Network¶

ISCC_MONITOR_ADDR: The HTTP listen address. Default :9464. Keep it on the internal network; see Reverse proxy.

All optional. Without them, the masthead shows neutral placeholder text.

ISCC_MONITOR_INSTANCE: The domain of the instance, for example monitor.example.com.
ISCC_MONITOR_OPERATOR: The line below the domain. Default: "independent Trust & Transparency service · ISCC-Hub network".
ISCC_MONITOR_REALM_NAME: The display name of the network, for example ISCC mainnet. It appears in the title of the hub list on the start page.

Operator co-branding¶

All optional. Branding shows them in use.

ISCC_MONITOR_OPERATOR_NAME

The organization that runs the instance. It appears as "Operated by ..." in the footer and as the text alternative of the logo. Required when ISCC_MONITOR_OPERATOR_URL or ISCC_MONITOR_OPERATOR_LOGO is set.

ISCC_MONITOR_OPERATOR_URL

The operator's website, an absolute http or https URL. The name and the logo link to it.

ISCC_MONITOR_OPERATOR_LOGO

Path to the operator's logo: .svg, .png, .webp or .jpg, at most 256 KiB, of the type its extension names. The monitor reads it once at startup and serves it at /_ds/operator-logo.

ISCC_MONITOR_FOOTER_LINKS

Footer links, such as an imprint or a privacy policy, as Label=URL pairs separated by |. Each URL is http, https or mailto:.

Imprint=https://example.com/imprint|Privacy=https://example.com/privacy

Example¶

A local instance for testnet with a short poll interval:

ISCC_MONITOR_DB=./monitor-test.db \
ISCC_MONITOR_REALM=https://raw.githubusercontent.com/iscc/iscc-hub/refs/heads/main/hubs/testnet.yaml \
ISCC_MONITOR_NORMAL=30s \
ISCC_MONITOR_ADDR=127.0.0.1:41464 \
iscc-monitor