Configuration

piway reads its settings from four layers. Each layer overrides the ones before it:

1. Built-in defaults
2. Config file (YAML)
3. Environment variables (PIWAY_*)
4. Command-line flags (only those given explicitly)

Run piway -print-config to see the effective configuration and which layer each value came from:

$ PIWAY_INTERVAL=2s piway -addr :9000 -print-config
# file: /home/user/.config/piway/config.yaml
addr: ":9000"  # flag -addr
interval: 2s  # env PIWAY_INTERVAL
stream_queue: 8  # default
log_level: warn  # file

The output is itself a valid config file.

Settings

Key	Env	Flag	Default	Description
addr	PIWAY_ADDR	-addr	":8080"	HTTP listen address.
interval	PIWAY_INTERVAL	-interval	1s	Metric collection interval, as a Go duration (500ms, 2s, 1m). Minimum 100ms.
stream_queue	PIWAY_STREAM_QUEUE	-stream-queue	8	Snapshots a WebSocket client may fall behind before it is disconnected with close code 1013.
log_level	PIWAY_LOG_LEVEL	-log-level	info	debug, info, warn or error.
data_dir	PIWAY_DATA_DIR	-data-dir	~/.local/state/piway	Where the metrics history is stored ($XDG_STATE_HOME/piway if that is set). An empty value disables recording; set it in the file or with -data-dir "", since an empty environment variable counts as unset.
flush_interval	PIWAY_FLUSH_INTERVAL	-flush-interval	1m	How long recorded samples may wait in memory before they are written. Longer means fewer SD card writes; a crash of piway loses up to this much history. 0 writes every sample. At most 10m. See STORAGE.md.
retention_raw	PIWAY_RETENTION_RAW	-retention-raw	24h	How long every sample is kept. Durations also accept days (7d); at least 1h.
retention_1m	PIWAY_RETENTION_1M	-retention-1m	7d	How long per-minute rollups are kept.
retention_1h	PIWAY_RETENTION_1H	-retention-1h	365d	How long per-hour rollups are kept.
webhook_secret	PIWAY_WEBHOOK_SECRET	-webhook-secret	empty	Secret shared with GitHub (webhook signatures) and GitLab (secret token), at least 16 characters. Empty disables webhooks. Never shown by -print-config. See DEPLOY.md.
webhook_url	PIWAY_WEBHOOK_URL	-webhook-url	found from Tailscale Funnel	The address GitHub reaches piway's webhook endpoint at, shown when you add a repository. Set it when piway is published another way (a Cloudflare Tunnel, a reverse proxy). See DEPLOY.md.
apps_file	PIWAY_APPS_FILE	-apps-file	~/.config/piway/apps.yaml	Repositories and branches that deploy on push.
proxy_domain	PIWAY_PROXY_DOMAIN	-proxy-domain	empty	Publish each app at <name>.<domain> through Caddy, such as local. A .local domain is also published on the LAN over mDNS. Empty disables it. See PROXY.md.
proxy_listen	PIWAY_PROXY_LISTEN	-proxy-listen	":8443"	Address Caddy serves apps on. Ports below 1024 need a sysctl change (PROXY.md).
proxy_tls	PIWAY_PROXY_TLS	-proxy-tls	true	Serve apps over HTTPS, with certificates from Caddy. false serves plain HTTP.
caddy_admin	PIWAY_CADDY_ADMIN	-caddy-admin	"localhost:2019"	Caddy's admin API.
alerts_file	PIWAY_ALERTS_FILE	-alerts-file	~/.config/piway/alerts.yaml	Alert rules. Missing means the built-in rules. See ALERTS.md.
notify_deploys	PIWAY_NOTIFY_DEPLOYS	-notify-deploys	all	Which deploys send a push notification: all (successes, rollbacks, restarts and failures), failures, or off. See ALERTS.md.
push_contact	PIWAY_PUSH_CONTACT	-push-contact	"https://github.com/OFK0/piway"	A mailto: or https: URL in the signed requests to push services, where they could reach the sender. See ALERTS.md.
password_file	PIWAY_PASSWORD_FILE	-password-file	~/.config/piway/password	The dashboard password's argon2id hash, written by -set-password. See Dashboard password.

The pattern is the same for every setting: the env var is PIWAY_ plus the key in upper case, and the flag is the key with _ replaced by -.

Dashboard password

$ piway -set-password
New dashboard password:
Again:
Password saved to /home/user/.config/piway/password. Signed-in browsers must sign in again.

It asks twice on a terminal, or reads one line from standard input otherwise (echo "$PW" | piway -set-password). The password needs at least 10 characters; piway stores only its argon2id hash, in password_file (mode 0600). A running piway picks a new password up at once, without a restart, and signs every browser out.

Until a password is set, piway answers only the Pi itself (API.md). To remove the password, delete the file.

Config file

The file is looked up in this order:

1. -config <file>
2. $PIWAY_CONFIG
3. $XDG_CONFIG_HOME/piway/config.yaml, usually ~/.config/piway/config.yaml

A file named by -config or PIWAY_CONFIG must exist. The default location is optional: if it is missing, piway runs on defaults.

The file is a flat YAML mapping. See deploy/config.example.yaml:

addr: "127.0.0.1:8080"
interval: 2s
log_level: debug

Quote addresses: in YAML, [::1]:8080 without quotes is a list.

Rules

• Typos are errors. An unknown key, a key set twice, or a nested value stops piway at startup with the file and line, instead of being silently ignored.
• Same parser everywhere. A value means the same thing in the file, in the environment and on the command line, and is validated the same way. Errors name the layer it came from: interval (from env PIWAY_INTERVAL): time: invalid duration "soon".
• Empty environment variables are ignored, so a blank Environment= line in a systemd unit does not override the file.
• A flag always wins, even when its value equals the default. Avoid flags in the systemd unit, or the config file cannot change that setting.
• Invalid configuration exits with status 2.