Substratum installer profile (v1)
This document defines substratum-installer-profile.json, a versioned artifact written by the desktop installer (apps/installer-gui) alongside per-device triangle manifests. It records deployment topology and mesh connectivity preferences separate from cryptographic triangle material in substratum-triangle-v1.md.
When it is used
- Written during self-hosted or (future) cloud-connected install on macOS, Windows, or Linux.
- Co-located with operational manifests under the platform install root (e.g.
~/.substratum/on macOS/Linux,C:\ProgramData\Substratum\on Windows). - Runtime components may merge triangle + profile at startup (see ADR 24).
JSON shape (schema_version 1)
| Field | Type | Required | Description |
|---|---|---|---|
schema_version | integer | yes | Must be 1. |
kind | string | yes | Must be substratum.installer.profile_v1. |
hosting_topology | string | yes | self_hosted or cloud_connected. |
mesh_mode | string | yes | private_hardware or cloud_relay. |
platform | string | yes | macos, windows, or linux. |
postgres_port | integer | yes | Personal-install Postgres listener; default 35432. |
gateway_bind_port | integer | yes | Internal gateway API bind; default 38080 (edge reverse-proxies here). |
edge_public_port | integer | yes | Public edge for UI + proxied API; default 35480 (avoids common 8080 and dev Compose 18080 conflicts). |
edge_hostname | string | yes | Local hostname for the edge URL (default substratum.localhost); .localhost names need no hosts file. Custom names may be registered in the OS hosts file during install. |
postgres_data_dir | string | yes | Absolute path to dedicated Substratum PG data directory. |
install_root | string | yes | Absolute path to Substratum home (manifests, web, blocks). |
postgres_source | string | yes | os — PostgreSQL tools from the OS package manager or PATH; dedicated cluster under postgres_data_dir. |
discovery_provider | string | no | e.g. tailscale, manual. |
Example (illustrative)
json
{
"schema_version": 1,
"kind": "substratum.installer.profile_v1",
"hosting_topology": "self_hosted",
"mesh_mode": "private_hardware",
"platform": "macos",
"postgres_port": 35432,
"gateway_bind_port": 38080,
"edge_public_port": 35480,
"edge_hostname": "substratum.localhost",
"postgres_data_dir": "/Users/alice/.substratum/postgres",
"install_root": "/Users/alice/.substratum",
"postgres_source": "os",
"discovery_provider": "tailscale"
}