## Actors - Maintainers The group developing and maintaining this project. We are creating the deployment workflows and service configurations, and curate changes proposed by contributors. - Contributors 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. - 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 configuration A specification for mapping components of a configuration to the runtime environment, e.g. which services to deploy to which virtual machines, or how to access object storage. - [NixOps4](https://nixops.dev) A tool to interact with mutable external resources based on declarations in the [Nix language](https://nix.dev/manual/nix/latest/language/). - 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. ## 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 between [actors](#actors) (depicted with rounded corners) and system components (see the [glossary](#glossary), depicted with rectangles). ![](https://git.fediversity.eu/Fediversity/meta/raw/branch/main/architecture-docs/interactions.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, 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) ## Break-down of project milestones Whereas details of the implementation may need to be decided as the technical challenges involved become clear, we can already give a higher-level planning of relevant milestones and some of their salient features: 1. [implement a way to run online services emphasising user autonomy and data portability](https://git.fediversity.eu/Fediversity/Fediversity/issues/347) 1. [Finalize architecture doc](https://git.fediversity.eu/Fediversity/Fediversity/issues/39) 1. [code-based migration data model](https://git.fediversity.eu/Fediversity/Fediversity/issues/103) 1. [migrating application data between hosting providers](https://git.fediversity.eu/Fediversity/Fediversity/issues/100) 1. [application offering generalised](https://git.fediversity.eu/Fediversity/Fediversity/issues/369) 1. [NixOS configuration as the core abstraction](https://git.fediversity.eu/Fediversity/Fediversity/issues/339) 1. [disseminate our results by engaging the open-source community to further expand on work in this direction](https://git.fediversity.eu/Fediversity/Fediversity/issues/348) 1. [automated dev-ops workflows](https://git.fediversity.eu/Fediversity/Fediversity/issues/224) 1. [external developers empowered to contribute](https://git.fediversity.eu/Fediversity/Fediversity/issues/288) 1. [exploit our work by enabling reproducible deployments of an initial set of portable applications](https://git.fediversity.eu/Fediversity/Fediversity/issues/349) 1. [applications deployed on command](https://git.fediversity.eu/Fediversity/Fediversity/issues/99) 1. [kick-started initial feedback cycle](https://git.fediversity.eu/Fediversity/Fediversity/issues/225) 1. [brought into production](https://git.fediversity.eu/Fediversity/Fediversity/issues/228) 1. [nix-less bootstrap](https://git.fediversity.eu/Fediversity/Fediversity/issues/332) 1. [key features improving user experience supported](https://git.fediversity.eu/Fediversity/Fediversity/issues/289)