441 lines
19 KiB
Markdown
441 lines
19 KiB
Markdown
<style>* {font-family: sans-serif;}</style>
|
|
|
|
## Actors
|
|
|
|
- Maintainers
|
|
|
|
The group maintaining this repository.
|
|
We are creating the deployment workflows and service configurations, and curate changes proposed by contributing developers.
|
|
|
|
- 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 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.
|
|
|
|
## Technologies used
|
|
|
|
### [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
|
|
|
|
#### [npins](https://github.com/andir/npins)
|
|
|
|
Npins is a dependency pinning tool for Nix which leaves recursive dependencies explicit, keeping the consumer in control.
|
|
|
|
Considered alternatives include:
|
|
|
|
- Flakes: defaults to implicitly following recursive dependencies, leaving control with the publisher.
|
|
|
|
### [SelfHostBlocks](https://nlnet.nl/project/SelfHostBlocks/)
|
|
|
|
SelfHostBlocks offers Nix module contracts to decouple application configuration from implementation details, empowering user choice by providing sane defaults yet a [unified interface](https://nlnet.nl/project/SelfHostBlocks/).
|
|
Offered contracts include back-ups, reverse proxies, single sign-on and LDAP.
|
|
In addition, we have been in contact with its creator.
|
|
|
|
Considered alternatives include:
|
|
|
|
- nixpkgs-provided NixOS service modules: support far more applications, but tightly coupled with service providers, whereas we expect them to [sooner or later](https://discourse.nixos.org/t/pre-rfc-decouple-services-using-structured-typing/58257) follow suit.
|
|
- NixOS service modules curated from scratch: would support any setup imaginable, but does not seem to align as well with our research-oriented goals.
|
|
|
|
### [OpenTofu](https://opentofu.org/)
|
|
|
|
OpenTofu is the leading open-source framework for infrastructure-as-code.
|
|
This has led it to offer a vibrant ecosystem of 'provider' plugins integrating various programs and services.
|
|
As such, it can facilitate automated deployment pipelines, including with — relevant to our project — hypervisors and DNS programs.
|
|
|
|
Considered alternatives include:
|
|
|
|
- Terraform: not open-source
|
|
|
|
### [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
|
|
|
|
### [PostgreSQL](https://www.postgresql.org/)
|
|
|
|
PostgreSQL is a relational database.
|
|
It is used by most of our applications.
|
|
|
|
Considered alternatives include:
|
|
|
|
- Sqlite: default option for development in many applications, but less optimized for performance, and less centralized for backups
|
|
|
|
### [Valkey](https://valkey.io/)
|
|
|
|
Valkey is a key-value store.
|
|
It is an open-source fork of Redis.
|
|
|
|
Considered alternatives include:
|
|
|
|
- Redis: not open-source
|
|
|
|
### [OpenSearch](https://opensearch.org/)
|
|
|
|
OpenSearch offers full-text search, and is used for this in many applications.
|
|
It is an open-source fork of ElasticSearch.
|
|
|
|
Considered alternatives include:
|
|
|
|
- ElasticSearch: not open-source
|
|
|
|
### [OctoDNS](https://github.com/octodns/octodns)
|
|
|
|
OctoDNS is a DNS server that may be configured using the Nix-native [NixOS-DNS](https://janik-haag.github.io/NixOS-DNS/).
|
|
|
|
Considered alternatives include:
|
|
|
|
- PowerDNS: offers a front-end option, but less geared toward the use-case of configuring by Nix
|
|
|
|
### [Authelia](https://github.com/authelia/authelia)
|
|
|
|
Authelia is a single sign-on provider that integrates with LDAP.
|
|
|
|
Considered alternatives include:
|
|
|
|
- KaniDM: does not do proper LDAP
|
|
- Authentik: larger package with focus on many things we do not need
|
|
- Keycloak: larger package with focus on many things we do not need
|
|
|
|
### [lldap](https://github.com/lldap/lldap)
|
|
|
|
Lldap is a light LDAP server, allowing to centralize user roles across applications.
|
|
|
|
Considered alternatives include:
|
|
|
|
- 389 DS: older larger package
|
|
- FreeIPA: wrapper around 389 DS
|
|
|
|
## Architecture
|
|
|
|
At the core of Fediversity lies a NixOS configuration module for a set of selected applications.
|
|
We will support 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 will further involve OpenTofu as an orchestrator.
|
|
We further provide a [reference front-end](https://git.fediversity.eu/Fediversity/Fediversity/src/branch/main/panel) to configure applications.
|
|
To ensure reproducibility, we also offer Nix packaging for our software.
|
|
|
|
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).
|
|
|
|
|
|
|
|
### 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. deployed applications: using the reproducible configuration module
|
|
1. application data:
|
|
- back-up/restore scripts [using SelfHostBlocks](https://shb.skarabox.com/contracts.html)
|
|
- application-specific migration scripts, to e.g. reconfigure of connections/URLs
|
|
|
|
### Data model
|
|
|
|
Whereas the bulk of our configuration logic is covered in the [configuration schema](#sample-configuration-schema), our reference front-end application does in fact store data.
|
|
The design for its data model to 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 VMs in question run Fediversity to offer our selected applications:
|
|
|
|
|
|
|
|
### Sample configuration schema
|
|
|
|
Whereas Nix(OS) option modules use Nix to specify types, in order to communicate the expected schema to other tools such as web applications, we use [JSON Schema](https://json-schema.org/) as an intermediate format, building upon [earlier work converting between such schemas by Nix collective Clan](https://clan.lol/blog/json-schema-converter/).
|
|
An example of such a schema might looks as follows:
|
|
|
|
```json
|
|
{
|
|
"$exportedModuleInfo": {
|
|
"path": []
|
|
},
|
|
"$schema": "http://json-schema.org/draft-07/schema#",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"domain": {
|
|
"$exportedModuleInfo": {
|
|
"path": [
|
|
"domain"
|
|
]
|
|
},
|
|
"default": "fediversity.net",
|
|
"description": "Apex domain under which the services will be deployed.\n",
|
|
"enum": [
|
|
"fediversity.net"
|
|
]
|
|
},
|
|
"enable": {
|
|
"$exportedModuleInfo": {
|
|
"path": [
|
|
"enable"
|
|
]
|
|
},
|
|
"default": false,
|
|
"description": "Whether to enable Fediversity configuration.",
|
|
"examples": [
|
|
true
|
|
],
|
|
"type": "boolean"
|
|
},
|
|
"initialUser": {
|
|
"$exportedModuleInfo": {
|
|
"path": [
|
|
"initialUser"
|
|
]
|
|
},
|
|
"default": null,
|
|
"description": "Some services require an initial user to access them.\nThis option sets the credentials for such an initial user.\n",
|
|
"oneOf": [
|
|
{
|
|
"type": "null"
|
|
},
|
|
{
|
|
"$exportedModuleInfo": {
|
|
"path": [
|
|
"initialUser"
|
|
]
|
|
},
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"displayName": {
|
|
"$exportedModuleInfo": {
|
|
"path": [
|
|
"initialUser",
|
|
"displayName"
|
|
]
|
|
},
|
|
"description": "Display name of the user",
|
|
"type": "string"
|
|
},
|
|
"email": {
|
|
"$exportedModuleInfo": {
|
|
"path": [
|
|
"initialUser",
|
|
"email"
|
|
]
|
|
},
|
|
"description": "User's email address",
|
|
"type": "string"
|
|
},
|
|
"password": {
|
|
"$exportedModuleInfo": {
|
|
"path": [
|
|
"initialUser",
|
|
"password"
|
|
]
|
|
},
|
|
"description": "Password for login",
|
|
"type": "string"
|
|
},
|
|
"username": {
|
|
"$exportedModuleInfo": {
|
|
"path": [
|
|
"initialUser",
|
|
"username"
|
|
]
|
|
},
|
|
"description": "Username for login",
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"displayName",
|
|
"email",
|
|
"password",
|
|
"username"
|
|
],
|
|
"type": "object"
|
|
}
|
|
]
|
|
},
|
|
"forgejo": {
|
|
"$exportedModuleInfo": {
|
|
"path": [
|
|
"forgejo"
|
|
]
|
|
},
|
|
"default": null,
|
|
"description": "Configuration for the Forgejo service\n",
|
|
"oneOf": [
|
|
{
|
|
"type": "null"
|
|
},
|
|
{
|
|
"$exportedModuleInfo": {
|
|
"path": [
|
|
"forgejo"
|
|
]
|
|
},
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"enable": {
|
|
"$exportedModuleInfo": {
|
|
"path": [
|
|
"forgejo",
|
|
"enable"
|
|
]
|
|
},
|
|
"default": false,
|
|
"description": "Whether to enable Forgejo.",
|
|
"examples": [
|
|
true
|
|
],
|
|
"type": "boolean"
|
|
}
|
|
},
|
|
"type": "object"
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"type": "object"
|
|
}
|
|
```
|
|
|
|
## 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 portability](https://git.fediversity.eu/Fediversity/Fediversity/issues/347)
|
|
- [deploying Fediversity applications](https://git.fediversity.eu/Fediversity/Fediversity/issues/99)
|
|
- [Initial internal user to kick-start feedback process](https://git.fediversity.eu/Fediversity/Fediversity/issues/225):
|
|
- automated provisioning of:
|
|
- [databases](https://git.fediversity.eu/Fediversity/Fediversity/issues/115)
|
|
- [object storage](https://git.fediversity.eu/Fediversity/Fediversity/issues/185)
|
|
- [virtual machines](https://git.fediversity.eu/Fediversity/Fediversity/issues/116)
|
|
- [DNS](https://git.fediversity.eu/Fediversity/Fediversity/issues/110)
|
|
- [admin accounts](https://git.fediversity.eu/Fediversity/Fediversity/issues/178)
|
|
- [SMTP service](https://git.fediversity.eu/Fediversity/Fediversity/issues/117)
|
|
- [email accounts](https://git.fediversity.eu/Fediversity/Fediversity/issues/118)
|
|
- [ephemeral state](https://git.fediversity.eu/Fediversity/Fediversity/issues/314)
|
|
- [specification published](https://git.fediversity.eu/Fediversity/Fediversity/issues/334)
|
|
- [ProxmoX back-end supports multiple users](https://git.fediversity.eu/Fediversity/Fediversity/issues/313)
|
|
- [user can have multiple deployments](https://git.fediversity.eu/Fediversity/Fediversity/issues/241)
|
|
- [users can update their deployment configurations](https://git.fediversity.eu/Fediversity/Fediversity/issues/158)
|
|
- [application data back-ups](https://git.fediversity.eu/Fediversity/Fediversity/issues/123)
|
|
- [migrating application data between hosting providers](https://git.fediversity.eu/Fediversity/Fediversity/issues/100)
|
|
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)
|
|
- [automated dev-ops workflows](https://git.fediversity.eu/Fediversity/Fediversity/issues/224):
|
|
- [separate test environments for staging vs. production](https://git.fediversity.eu/Fediversity/Fediversity/issues/69)
|
|
- [continuous deployment](https://git.fediversity.eu/Fediversity/Fediversity/issues/177)
|
|
- [CI rejects failing deployments](https://git.fediversity.eu/Fediversity/Fediversity/issues/102)
|
|
- [Nix package overlays upstreamed](https://git.fediversity.eu/Fediversity/Fediversity/issues/248)
|
|
- [facilitate suggestions in PR reviews](https://git.fediversity.eu/Fediversity/Fediversity/issues/302)
|
|
- [integration test](https://git.fediversity.eu/Fediversity/Fediversity/issues/277)
|
|
- [external developers empowered to contribute](https://git.fediversity.eu/Fediversity/Fediversity/issues/288):
|
|
- [NixOS configuration as the core abstraction](https://git.fediversity.eu/Fediversity/Fediversity/issues/339)
|
|
- [integration tests](https://git.fediversity.eu/Fediversity/Fediversity/issues/277)
|
|
- [Continuous Integration builds available in a public cache](https://git.fediversity.eu/Fediversity/Fediversity/issues/92)
|
|
- [reproducible project infrastructure](https://git.fediversity.eu/Fediversity/Fediversity/issues/336)
|
|
- [continuous deployment](https://git.fediversity.eu/Fediversity/Fediversity/issues/177)
|
|
- [separate staging/testing environments](https://git.fediversity.eu/Fediversity/Fediversity/issues/69)
|
|
- [code reviewers can suggest changes](https://git.fediversity.eu/Fediversity/Fediversity/issues/302)
|
|
- [knowledge base](https://git.fediversity.eu/Fediversity/Fediversity/issues/288)
|
|
- [module upstreamed to nixpkgs](https://git.fediversity.eu/Fediversity/Fediversity/issues/333)
|
|
1. [Exploit our work by facilitating the sample use-case of web hosting organisations using an initial set of services](https://git.fediversity.eu/Fediversity/Fediversity/issues/349)
|
|
- [Software ready for web hosts to take into production](https://git.fediversity.eu/Fediversity/Fediversity/issues/228):
|
|
- [garbage collection of unallocated resources](https://git.fediversity.eu/Fediversity/Fediversity/issues/188)
|
|
- [Nix-less bootstrap](https://git.fediversity.eu/Fediversity/Fediversity/issues/332)
|
|
- [ensure hosts may update users' deployments](https://git.fediversity.eu/Fediversity/Fediversity/issues/159)
|
|
- [reference front-end decoupled from version of configuration module](https://git.fediversity.eu/Fediversity/Fediversity/issues/304)
|
|
- [security audit](https://git.fediversity.eu/Fediversity/Fediversity/issues/291)
|
|
- [Key features improving user experience supported](https://git.fediversity.eu/Fediversity/Fediversity/issues/289):
|
|
- [enqueuing deployment syncs](https://git.fediversity.eu/Fediversity/Fediversity/issues/242)
|
|
- [provide single sign-on](https://git.fediversity.eu/Fediversity/Fediversity/issues/212)
|
|
- [upstream configuration options exposed](https://git.fediversity.eu/Fediversity/Fediversity/issues/195)
|
|
- [allow disabling application while retaining data](https://git.fediversity.eu/Fediversity/Fediversity/issues/186)
|
|
- [ProxmoX deployment allows scaling resources assigned to a VM](https://git.fediversity.eu/Fediversity/Fediversity/issues/119)
|
|
- [aid needed user actions on schema update](https://git.fediversity.eu/Fediversity/Fediversity/issues/214)
|
|
- [completed initial application offering](https://git.fediversity.eu/Fediversity/Fediversity/issues/350)
|
|
- [pooling application instances to shared VMs](https://git.fediversity.eu/Fediversity/Fediversity/issues/322)
|
|
- [allow use of external single sign-on](https://git.fediversity.eu/Fediversity/Fediversity/issues/161)
|
|
- [on migration, allow reconfiguring monolithic vs distributed](https://git.fediversity.eu/Fediversity/Fediversity/issues/341)
|