Configuration data flow

This page tells how an operator configuration becomes a deployment. The data model and hosting resources pages are the option references for the same parts. The concepts page defines the terms.

From a configuration to a deployment

flowchart
  subgraph configuration
    application-config
  end
  subgraph resource[resource module]
    request
    policy
  end
  subgraph application[application module]
    application-options{{application-options}} --> application-config
    application-config --> config-mapping
    request{{request}} --> config-mapping
    config-mapping(config-mapping)
  end
  subgraph fediversity[fediversity setup]
    config-mapping -->|required resources| resource-mapping(resource-mapping)
    policy{{policy}} --> provider-config -->|available resources| resource-mapping -->|configuration| deployment{deployment}
  end
  maintainer((maintainer)) -->|curates| resource
  contributor((developer)) -->|curates| application
  operator((operator)) -->|enters| configuration
  hosting-provider((hosting provider)) -->|maintains| fediversity

In the diagram, a circle is an actor, a box with angled sides is a type, a rectangle is a value, a box with round corners is a function, and a diamond is a state. An arrow points to the part that uses the other part. An application module is a component that the operator can select.

1. The operator selects the applications and sets their options in the panel. The panel form comes from frontendConfiguration, which has only the operator-facing components. The result is a configuration.
2. Each enabled component maps its options to the resources that it needs. The implementation of a component, a config-mapping, returns one request for each resource, keyed by an instance name. For example, Forgejo requests a TLS certificate as "tls".ssl, its secrets as "age".secrets, and outbound mail as "forgejo-smtp".smtp.
3. The hosting provider declares an environment. Its resources set the policy of each resource: which provider gives the resource, and with which limits.
4. The implementation of the environment, a resource-mapping, collects the requests of all components. For each resource, the process function of the policy turns the requests into NixOS modules or OpenTofu resources.
5. The result is a deployment for an effect, for example a set of Incus containers that OpenTofu creates and NixOS configures.

environments.<env>.deployment does all of these steps for one deployment.

Resources

A resource is the interface between a component and a hosting provider. The component sets the request, and the hosting provider sets the policy. The request/policy resource pattern on the data model page tells more, and the hosting resources page lists the request options of each resource.

A resource is not a contract of RFC 189. A resource usually uses one or more such contracts to give what a request asks for. The Contracts (RFC 189) page tells how.

Where the code is

Further reading

• The configuration data flow of the Fediversity architecture.
• The data model review of 2025-07-03.