Advanced Configuration Path

Advanced configuration is not a pile of fields. Fix the runtime boundary first, then enable the features you need.

1. Fix the Public URL

Choose the single public root URL for Dash:

app:
  public_url: "https://dash.example.com"

This affects:

• Browser access.
• Node install script download URLs.
• Node target URLs.
• Reverse proxy paths.

Rules:

• Scheme can be omitted; IPs default to http, domain names default to https.
• Production deployments should explicitly use an HTTPS domain and reverse-proxy to the Dash backend through Nginx or Caddy.
• IP+HTTP is only for local validation or temporary internal testing, not as a long-term public entrypoint.
• The final URL must not contain a path prefix.
• After changing public_url, new node install commands should use the new address.
• Existing node report.yaml files are not rewritten automatically.

2. Choose Runtime State Backend

Production:

redis:
  addr: 127.0.0.1:6379

Fallback:

dash --no-redis

Redis stores:

• Sessions.
• Hot snapshots.
• Alert runtime state.

PostgreSQL stores:

• Metrics history.
• Traffic facts and summaries.
• Nodes and groups.
• Alert rules and notification outbox.
• System settings.
• Theme metadata.

3. Set Retention

Normal monitoring:

database:
  retention_days: 45
  traffic_retention_days: 45

Traffic billing:

database:
  retention_days: 45
  traffic_retention_days: 90

When omitted, traffic_retention_days uses max(retention_days, 45). Do not make traffic retention too short if P95 review is required.

4. Enable Guest Access

Historical metrics guest access:

history_guest_access_mode = by_node

Traffic guest access:

traffic.guest_access_mode = by_node

Both still respect each node's is_guest_visible setting.

5. Configure Traffic Accounting

Choose the mode first:

Mode	Use
lite	Monthly inbound/outbound total and estimated peak
billing	5-minute facts, daily summary, P95, coverage, monthly snapshot

Choose the billing cycle:

Cycle	Use
calendar_month	Calendar month
whmcs_compatible	WHMCS-style anchored cycle
clamp_to_month_end	Clamp start day to month end

Choose the direction:

Direction	Meaning
out	outbound only
both	inbound + outbound
max	max(inbound, outbound)

See Traffic Accounting.

6. Configure Alerts

Built-in rules:

ID	Metric	Meaning
-1	node.offline	node offline
-2	raid.failed	RAID failure

For custom rules, choose metric and threshold first, then mount to nodes or groups. Prefer group mounts over copying the same rule for every node.

core_plus only applies to:

• cpu.load1
• cpu.load5
• cpu.load15

Cooldown must be greater than or equal to 0. Duration must use supported presets. See Alert Rules.

7. Configure Notifications

Supported channels:

• Telegram bot.
• Telegram MTProto.
• Email SMTP.
• Webhook.

Recommendations:

• Validate channels with a test rule first.
• Set an explicit TLS mode for email.
• Use a secret and verify HMAC for webhooks.
• Avoid too many duplicate channels for the same severe alert.

See Notifications.

8. Theme Customization

Themes change CSS tokens and recipes, not frontend code.

Package structure:

theme.json
tokens.css
recipes.css
preview.png
README.md

Constraints:

• theme.json and tokens.css are required.
• Theme IDs use [a-z0-9][a-z0-9_-]{0,63}.
• default and built-in theme IDs are reserved.
• CSS is restricted to allowed selectors and custom properties.

See Theme Authoring.

9. Adjust Node Config

Node report URLs live locally:

• Linux/macOS: /var/lib/ithiltir-node/report.yaml
• Windows: %ProgramData%\Ithiltir-node\report.yaml

Common commands:

./ithiltir-node report list
./ithiltir-node report update <id> '<new-secret>'
./ithiltir-node report install https://dash.example.com/api/node/metrics '<node-secret>'

Use install to change the URL. Use update only to rotate a key.

10. Verify

Dash:

curl -fsS https://dash.example.com/api/version/
journalctl -u dash.service -n 100 --no-pager

Node:

systemctl status ithiltir-node.service
journalctl -u ithiltir-node.service -n 100 --no-pager

API/UI:

• Log in to the admin console.
• Check system settings.
• Check latest node snapshots.
• Check historical metrics.
• Check monthly traffic statistics.
• Trigger one test alert notification.