From b7b7a651d3066c474fc716caf5af615f2a9a8b22 Mon Sep 17 00:00:00 2001 From: cinereal Date: Wed, 9 Jul 2025 15:47:46 +0200 Subject: [PATCH] upstream architecture document --- architecture.md | 168 ------------------------------------------------ fediversity.md | 2 +- 2 files changed, 1 insertion(+), 169 deletions(-) delete mode 100644 architecture.md diff --git a/architecture.md b/architecture.md deleted file mode 100644 index b9f541f..0000000 --- a/architecture.md +++ /dev/null @@ -1,168 +0,0 @@ -# Fediversity Implementation and planning - -## Actors - -- Maintainers - - The group developing and maintaining this project. - We are creating the deployment workflows and service configurations, and curate changes proposed by contributors. - -- Developers - - People with the technical background to engage with our work, and may contribute back, build on top of, remix, or feel inspired by our work to create something better. - -- 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) configured by operators and used by users. - -- Configuration - - A collection of settings for a piece of software. - - > Example: Configurations are deployed to VMs. - -- Provision - - Make a resource, such as a virtual machine, available for use. - -- Deploy - - Put software onto computers. - The software includes technical configuration that links software components. - -- Migrate - - Move service configurations and deployments (including user data) from one hosting provider to another. - -- Run-time backend - - A type of digital environment one can run operating systems such as NixOS on, e.g. bare-metal, a hypervisor, or a container run-time. - -- Provider - - An interface against which we deploy to a run-time backend. - -- Provider configuration - - A configuration that specifies resources made available to deploy to and how to access these. - -- Resource - - A resource is any external entity that we need for our set-up - This may include e.g. hypervisors, file systems, DNS entries, VMs or object storage instances. - -## Technologies used - -This is an incomplete and evolving list of core components planned to be used in this project. -It will grow to support more advanced use cases as the framework matures. - -### Nix and [NixOS](https://nixos.org/) - -NixOS is a Linux distribution with a [vibrant](https://repology.org/repositories/graphs), [reproducible](https://reproducible.nixos.org/) and [security-conscious](https://tracker.security.nixos.org/) ecosystem. -As such, we see NixOS as the only viable way to reliably create a reproducible outcome for all the work we create. - -Considered alternatives include: - -- containers: do not by themselves offer the needed reproducibility - -### [Proxmox](https://proxmox.com/) - -Proxmox is a hypervisor, allowing us to create VMs for our applications while adhering to our goal of preventing lock-in. -In addition, it has been [packaged for Nix](https://github.com/SaumonNet/proxmox-nixos) as well, simplifying our requirements to users setting up our software. - -Considered alternatives include: - -- OpenNebula: seemed less mature - -### [Garage](https://garagehq.deuxfleurs.fr/) - -Garage is a distributed object storage service. -For compatibility with existing clients, it reuses the protocol of Amazon S3. - -Considered alternatives include: - -- file storage: less centralized for backups - -## Architecture - -At the core of Fediversity lies a NixOS configuration module for a set of selected applications. - -- We will enable using it with **different run-time environments**, such as a single NixOS machine or a ProxmoX hypervisor. -- Depending on the targeted run-time environment, deployment may involve [NixOps4](https://nixops.dev) or [OpenTofu](https://opentofu.org/) as an **orchestrator**. -- We further provide demo front-end for **configuring applications** and configuring **run-time backends**. - -To ensure reproducibility, all software will be packaged with Nix. - -To reach our goals, we aim to implement the following interactions. - -The used legend is as follows: - -- Circle: [actor](#actors) -- Angled box: type -- Rectangle: value -- Rounded box: function -- Diamond: state -- Arrow: points towards dependant - -For further info on components see the [glossary](#glossary). - -![](https://git.fediversity.eu/Fediversity/meta/raw/branch/main/architecture-docs/interactions-migration.svg) -### Configuration data flow - -This data flow diagram refines how a deployment is obtained from an operator's application configuration and a hosting provider's runtime setup. - -An **application module** specifies operator-facing **application options**, and a **configuration mapping** which determines the application's underlying implementation. Application modules can be supplied by external developers, which would curate application modules against that interface. - -For its runtime setup, a hosting provider has to supply a **resource mapping** that would take their self-declared **provider configuration** (which determines the *available* resources) and the output of an application's resource mapping (which determine resource *requirements*) and produce a **configuration**. This configuration ships with a mechanism to be *deployed* to the infrastructure (which is described by the environment, and features the required resources), where it will accumulate **application state**. - -Applications and runtime environments thus interface through **resources**, the properties of which are curated by Fediversity maintainers. - -![](https://git.fediversity.eu/Fediversity/meta/raw/branch/main/architecture-docs/interactions-fediversity.svg) - - -### Service portability - -The process of migrating one's applications to a different host encompasses: - -1. Domain registration: involves a (manual) update of DNS records at the registrar -1. Deploy applications: using the reproducible configuration module -1. Copy application data: - - Run back-up/restore scripts - - Run application-specific migration scripts, to e.g. reconfigure connections/URLs - -### Data model - -Whereas the bulk of our configuration logic is covered in the configuration schema, [implemented here](https://git.fediversity.eu/Fediversity/Fediversity/src/branch/main/deployment/data-model.nix) and [tested here](https://git.fediversity.eu/Fediversity/Fediversity/src/branch/main/deployment/data-model-test.nix), our reference front-end applications will store data. -The data model design for the configuration front-end needed support the desired functionality is as follows, using the crow's foot notation to denote cardinality: - - - -### Host architecture - -Whereas the core abstraction in Fediversity is a NixOS configuration module, a more full-fledged example architecture of the web host use-case we aim to support as part of our exploitation would be as follows, where virtual machines in question run Fediversity to offer our selected applications: - -![](https://git.fediversity.eu/Fediversity/meta/raw/branch/main/architecture-docs/host-architecture.png) diff --git a/fediversity.md b/fediversity.md index d23a6dd..2bd56c3 100644 --- a/fediversity.md +++ b/fediversity.md @@ -292,7 +292,7 @@ We will integrate that aspect into the high level process on a best effort basis # Implementation and planning -See the split-out architecture document. +See the split-out [architecture document](https://git.fediversity.eu/Fediversity/meta/src/branch/main/architecture-docs/architecture.md). ## Work plan and resources