upstream architecture document
This commit is contained in:
parent
bfea8fcb80
commit
b7b7a651d3
SSH key fingerprint:
SHA256:COspvLoLJ5WC5rFb9ZDe5urVCkK4LJZOsjfF4duRJFU
2 changed files with 1 additions and 169 deletions
168
architecture.md
168
architecture.md
|
|
@ -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).
|
||||
|
||||
|
||||
### 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.
|
||||
|
||||
|
||||
|
||||
|
||||
### 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:
|
||||
|
||||
<img src="https://git.fediversity.eu/Fediversity/meta/raw/branch/main/architecture-docs/panel-data-model.svg" alt="" style="max-width:600px;"/>
|
||||
|
||||
### 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:
|
||||
|
||||
|
||||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue