Manual Deployment

Not An Install Procedure

The maintained install path is frameworks cluster provision for platform-managed clusters and frameworks edge deploy for tenant-owned BYO edge nodes. This page is a break-glass map of the moving parts behind those commands. It intentionally does not duplicate service env files, systemd units, SQL bootstrap inserts, or rendered CLI output.

Manual deployment instructions go stale quickly because the current system is manifest-driven. Treat these sources as authoritative for the current release:

Surface	Source of truth
Platform deployment workflow	Deployment Overview and frameworks cluster provision --help
BYO edge deployment workflow	frameworks setup, frameworks login, and frameworks edge deploy --help
Cluster shape, hosts, service placement, DNS inputs	Cluster Manifest
Manifest resolution and provisioning behavior	cli/pkg/inventory/, cli/cmd/cluster_provision*.go, cli/pkg/orchestrator/, cli/pkg/provisioner/
Ansible-backed infrastructure roles	Ansible Provisioning and ops/ansible/
Public DNS service types and labels	DNS and Cluster Routing and pkg/dns/public_services.go
Base environment inputs and derived runtime values	External Services, config/env/base.env, and config/env/secrets.env.example
PostgreSQL/YugabyteDB schemas and migrations	Postgres Migrations and pkg/database/sql/
ClickHouse schema and migrations	ClickHouse Migrations and pkg/database/sql/clickhouse/
Mesh identity and Privateer bootstrap	Mesh Bootstrap
Upgrade behavior	Running Upgrades

Current Deployment Paths

Platform-Managed Cluster

Use this path when the operator runs the FrameWorks control plane.

frameworks cluster provision --manifest cluster.yaml
frameworks cluster doctor
frameworks cluster status

cluster provision resolves the manifest, validates host and mesh state, plans the dependency graph, provisions infrastructure, initializes databases, applies static reference seeds, reconciles service-owned bootstrap state, syncs edge release targets, and validates health. The command is read-only against GitOps: it consumes cluster.yaml, optional hosts_file, and referenced env files; it does not rewrite those sources.

Tenant-Owned BYO Edge

Use this path when the operator owns an edge node but not the FrameWorks core.

frameworks setup
frameworks login
frameworks edge deploy --ssh ubuntu@edge-1 --email [email protected]

The selfhosted persona is a BYO edge persona. It uses public Bridge flows for cluster setup, enrollment-token issuance, and Foghorn pre-registration. It does not ask the operator to run Quartermaster or Foghorn, and it does not use frameworks cluster nodes.

Deployment Layers

Manifest And Secrets

The manifest describes hosts, services, infrastructure, interfaces, observability, DNS ownership, release channel, and cluster definitions. Secrets come from referenced env files, normally SOPS-encrypted in GitOps. For current field names and examples, use Cluster Manifest and External Services.

Do not maintain a separate manual list of service env vars. Some values are operator-owned inputs, while others are generated by config rendering or derived at runtime. The environment standard documents that split, and the CLI renders the concrete files during provisioning.

Databases

Fresh platform provisioning applies embedded baseline schemas and migration phases through the CLI. Static reference data comes from pkg/database/sql/seeds/static/; demo data is separate and only for development or test stacks.

Manual SQL inserts for platform tenants, clusters, service rows, or pricing are not a supported bootstrap procedure. Those rows are reconciled from the manifest and service-owned bootstrap code during cluster provision.

Networking And DNS

Backend service-to-service traffic uses the private mesh or equivalent private network. Edge nodes are public-facing and do not join the backend mesh. Privateer and systemd-resolved provide .internal resolution for managed mesh hosts.

Navigator reconciles public DNS from the service type tables in pkg/dns/public_services.go. Media services are cluster-scoped; root API and web services live under the root public domain. Avoid copying DNS tables from a manual guide into automation. Use the manifest plus DNS and Cluster Routing.

Services

Provisioning is role-based:

• Infrastructure services use dedicated provisioner roles.
• Generic FrameWorks Go services use the service role, in Docker or native mode according to the manifest.
• Interfaces and reverse proxies use their own provisioners.
• Edge nodes are handled by the edge deployment pipeline, not by a hand-written Quartermaster/Foghorn install on the tenant’s host.

For current service IDs and default ports, use the CLI and code-backed references: frameworks cluster diagnose ports --help, cli/pkg/provisioner/registry.go, and pkg/servicedefs/servicedefs.go.

Break-Glass Checks

When a provisioned cluster is not healthy, start with read-only CLI checks:

frameworks cluster detect
frameworks cluster doctor --deep
frameworks cluster status
frameworks cluster drift
frameworks cluster logs <service>

When a BYO edge is not healthy, stay on the edge path:

frameworks edge status --ssh ubuntu@edge-1
frameworks edge doctor --dir /opt/frameworks-edge
frameworks edge logs --ssh ubuntu@edge-1

Use manual host inspection only after the relevant CLI command narrows the failure to a host, service, database, DNS record, certificate, or migration ledger. At that point, inspect the generated files and service manager on the target host; do not back-port those generated files into this page.

What This Page No Longer Tries To Do

This page does not provide:

• Static CLI output samples.
• Hand-authored service env files.
• Hand-authored systemd units.
• Manual SQL bootstrap inserts.
• A standalone Kafka topic checklist.
• A separate service port table.
• A self-hosted edge guide that tells tenants to run Quartermaster or Foghorn.

Those details are owned by the CLI, manifests, schemas, migration code, and service definitions. Keeping them in those source-of-truth surfaces prevents this reference from drifting away from the current release.