diff --git a/fediversity.md b/fediversity.md index 4536e3c..3ce983a 100644 --- a/fediversity.md +++ b/fediversity.md @@ -434,6 +434,139 @@ We will integrate that aspect into the high level process on a best effort basis # Quality and efficiency of the implementation +## Interactions + +To reach these goals, we aim to implement the following interactions between [actors](#actors) (depicted with rounded corners) and system components (see the [glossary](#glossary), depicted with rectangles). + +```mermaid +flowchart + + user(user) --> |use| deployment + + configuration -->|deploy| deployed + devs(developers) --> |maintain| fediversity + + fediversity --> |update| provider1 + subgraph provider1["fediversity setup A"] + subgraph panel1[panel] + configuration[staged configuration] + configuration --> |update| configuration + deployed[deployed configuration] + end + deployed --> |describe| deployment + provider-config[runtime config] --> |describe| host + provider-config --> |implement runtime interfaces| panel1 + subgraph host[runtime environment] + deployment[applications] + state + end + end + + deployment --> |store| state + + operator(operator) --> |change| configuration + + subgraph provider2["fediversity setup B"] + subgraph panel2[panel] + configuration2[staged configuration] + deployed2[deployed configuration] + end + subgraph host2[runtime environment] + deployment2[applications] + state2[state] + end + end + + operator --> |trigger| migration + configuration & deployed & state --> migration + migration --> configuration2 & deployed2 & state2 + provider(hosting provider) --> |maintain| provider1 + subgraph fediversity[fediversity source code] + applications[application modules] + backends[runtime backends] + config[runtime options] + end +``` + +## Actors + +- Developers + + The group working on this repository. + We are creating the deployment workflows and service configurations. + +- Hosting provider + + They provide and maintain the physical infrastructure, and run the software in this repository, through which operators interact with their deployments. + Hosting providers are technical administrators for these deployments, ensuring availability and appropriate performance. + + We target small- to medium-scale hosting providers with 20+ physical machines. + +- Operator + + They select the applications they want to run. + They don't need to own hardware or deal with operations. + Operators administer their applications in a non-technical fashion, e.g. as moderators. + They pay the hosting provider for registering a domain name, maintaining physical resources, and monitoring deployments. + +- User + + They are individuals using applications run by the operators, and e.g. post content. + +## Glossary + +- [Fediverse](https://en.wikipedia.org/wiki/Fediverse) + + A collection of social networking applications that can communicate with each other using a common protocol. + +- Application + + User-facing software (e.g. from Fediverse) run by the hosting provider for an operator. + +- Configuration + + A collection of settings for a machine running NixOS. + + > Example: Configurations are deployed to VMs. + +- Provision + + Make a resource, such as a virtual machine, available for use. + +- Deploy + + Put software, such as applications, onto computers. + The software includes technical configuration that links software components. + In our context, this a Configuration deployed to a runtime environment. + Most user-facing configuration remains untouched by the deployment process. + +- Migrate + + Move service configurations and deployment (including user data) from one hosting provider to another. + +- Resource + + A [resource for NixOps4](https://nixops.dev/manual/development/concept/resource.html) is any external entity that can be declared with NixOps4 expressions and manipulated with NixOps4, such as a virtual machine, an active NixOS configuration, a DNS entry, or customer database. + +- Resource provider + + A resource provider for NixOps4 is an executable that communicates between a resource and NixOps4 using a standardised protocol, allowing [CRUD operations](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete) on the resources to be performed by NixOps4. + Refer to the [NixOps4 manual](https://nixops.dev/manual/development/resource-provider/index.html) for details. + + > Example: We need a resource provider for obtaining deployment secrets from a database. + +- Runtime backend + + A type of digital environment one can run operating systems such as NixOS on, e.g. bare-metal, a hypervisor, or a container runtime. + +- Runtime environment + + The thing a deployment runs on, an interface against which the deployment is working. See runtime backend. + +- Runtime config + + Configuration logic specific to a runtime backend, e.g. how to deploy, how to access object storage. + ## Architecture At the core of Fediversity lies a Terraform module for setting up NixOS instances on a hypervisor, so far targeting ProxmoX. @@ -450,7 +583,7 @@ Whereas details of the implementation may need to be decided as the technical ch - Initial internal user to kick-start feedback process: - automate provisioning of: - [databases](https://git.fediversity.eu/Fediversity/Fediversity/issues/115) - - [immutable storage](https://git.fediversity.eu/Fediversity/Fediversity/issues/185) + - [object storage](https://git.fediversity.eu/Fediversity/Fediversity/issues/185) - [virtual machines](https://git.fediversity.eu/Fediversity/Fediversity/issues/116) (and related resources) - [DNS](https://git.fediversity.eu/Fediversity/Fediversity/issues/110) - [SMTP service](https://git.fediversity.eu/Fediversity/Fediversity/issues/117)