Configuration Architecture & Syntax (Starry v3.0)
In Starry v3.0, the configuration engine is powered by the pure functional library Starry.Dsl (written in F#). The entire cluster infrastructure is modeled as an immutable graph with whole-subtree substitution, object inheritance via $:, and inline secret interpolation.
1. Unified Config Graph AST & File Layout
Every file and directory within the configuration path is mounted into a single immutable AST:
- Structured Files (
.yaml,.json,.toml): Parsed and mounted to their respective tree branches (e.g.nodes/germany.yaml->root.nodes.germany). - Raw Text Files (
files/*): Text files (such asfiles/nginx.conforfiles/init.sql) are mounted asStringNodeobjects under their path (root.files.["nginx.conf"]). - Custom Branches: Users can organize arbitrary user branches (
presets,secrets,vars,dns_providers,backups,certs) without schema rejection.
2. Graph References ($) & Object Inheritance ($:)
Whole-Subtree Substitution
When a property references a graph path (e.g. env: "$presets.db_env"), Starry replaces the reference with a deep copy of the resolved subtree:
presets:
db_env:
POSTGRES_DB: "starry"
POSTGRES_USER: "admin"
POSTGRES_PASSWORD: "ENC[AES256_GCM:v1:...]"
services:
database:
image: "postgres:16"
env: "$presets.db_env"Inheritance & Merging ($:)
Using the special "$" key, a service or node can inherit and merge properties from one or more base presets:
presets:
base_service:
restart: "always"
priority: 50
networks: ["$networks.app_net"]
services:
web:
$: "$presets.base_service"
image: "nginx:alpine"
priority: 80 # Overrides priority from base_serviceString & File Interpolation
All strings and text files support $path.to.value and ${path.to.value} interpolation, with automatic secret decryption during deployment.
3. IPv6 Mesh (fd67:b00b::/32) & Monotonic ID Ledger
- Cluster ULA Prefix:
fd67:b00b::/32. - Host Subnet (
/48): Each node is assignedfd67:b00b:<host_id>::/48. WireGuard interfacestarry0has addressfd67:b00b:<host_id>::1/32, and peers routeAllowedIPs = fd67:b00b:<host_id>::/48statically. - Container Replica Subnet (
/64): Each container replica gets a dedicated/64subnetfd67:b00b:<host_id>:<container_id>::/64with a single interfaceeth0bound tofd67:b00b:<host_id>:<container_id>::1/64. - Tombstone Ledger (
.starry/id-ledger.json): Released host and container IDs are permanently tombstoned and never reused.
4. Named Bidirectional Routing (ports:)
ports:
shop_https_v4:
from: "$nodes.germany.ipv4:443"
to: "$ingress:443"
proto: "tcp"
bidirectional: true # Inbound DNAT + symmetric outbound SNAT!
custom_proxy:
from: "$nodes.finland.ipv4:443"
to: "my-proxy:443"5. Managed Ingress ($ingress) & L4 SNI Proxying
$ingressbinds internally tofd67:b00b:<host_id>:ffff::1and never intercepts port 443 without explicit rules inports:.- Routing uses Nginx
stream { ssl_preread on; }:sni: "<target>"passes TLS traffic through at Layer 4 without certificate termination.http: "<target>"routes internally tohttp {}for SSL termination and reverse proxying.
6. Hierarchical Domains (domains:) & Cloudflare Origin Rules
domains:
rocks:
bocchi:
dns_provider: "$dns_providers.cf"
cert: "$certs.bocchi_wildcard"
node: "$nodes.germany"
"@":
http: "landing:80"
shop:
http: "shop-web:3000"
vpn:
sni: "xray:8443"
proxy_protocol: trueWhen an ingress entry port is non-standard (e.g. 8443), Starry automatically programs Cloudflare Origin Rules via the Rulesets API to rewrite origin ports transparently!