docs: update references to renamed commons repository (#11)
This commit is contained in:
deytenit authored and 
GitHub committed
1 parent
6b0a893c86
commit
8dba55272c
12 files changed
+461
-3
No files matched your search
@@ -0,0 +1,14 @@
|
||||
---
|
||||
title: Concepts
|
||||
description: Theoretical foundations, architecture, and security models.
|
||||
weight: 10
|
||||
---
|
||||
|
||||
Theoretical foundations, architecture, and security models for the Root infrastructure framework.
|
||||
|
||||
{{% cards %}}
|
||||
{{< card link="principles" title="Infrastructure principles" icon="book-open" subtitle="Predictability, minimal dependencies, and decentralization." >}}
|
||||
{{< card link="architecture" title="Infrastructure architecture" icon="share" subtitle="Decentralized orchestration and deployment models." >}}
|
||||
{{< card link="security-model" title="Security & privilege isolation" icon="shield-check" subtitle="Privilege isolation and network hardening." >}}
|
||||
{{< card link="tiered-storage" title="Tiered storage model" icon="database" subtitle="Standardized storage classification for service data." >}}
|
||||
{{% /cards %}}
|
||||
@@ -0,0 +1,55 @@
|
||||
---
|
||||
title: Infrastructure architecture
|
||||
description: The decentralized orchestration model and deployment structure.
|
||||
weight: 10
|
||||
---
|
||||
|
||||
The Root framework operates on a decentralized orchestration model designed for independent, self-contained projects. It enforces a strict separation between the orchestrator (the "brain") and the automation tasks (the "muscle").
|
||||
|
||||
## Core philosophy {#philosophy}
|
||||
|
||||
The framework is built on the **Smart Root, Stupid Actions** principle. This design ensures that individual automation scripts remain declarative and unaware of the global system state, while the central dispatcher handles environment resolution and library initialization.
|
||||
|
||||
### Smart Root (The Dispatcher)
|
||||
|
||||
The `root` entrypoint is the sole interface for users. It is responsible for:
|
||||
|
||||
- **Environment resolution** → Locating the `commons` and `configs` repositories.
|
||||
- **Library warming** → Sourcing namespaced modules exactly once.
|
||||
- **Context establishment** → Defining the target [Node](/root/glossary#node) and its associated paths.
|
||||
|
||||
### Stupid Actions (The Tasks)
|
||||
|
||||
[Actions](/root/glossary#action) are declarative scripts located in `scripts/actions/`. They are "stupid" because:
|
||||
|
||||
- They do not calculate paths or detect repositories.
|
||||
- They depend entirely on the `ROOT_` environment variables.
|
||||
- They focus exclusively on a single atomic task (e.g., `compose`, `ufw`).
|
||||
|
||||
## Deployment model {#deployment}
|
||||
|
||||
The framework is typically deployed as a shared [Commons](/root/glossary#commons) repository mounted as a Git submodule within a configuration repository. The engine powering this shared infrastructure is hosted at [GitHub: ermnvldmr.com-root-commons](https://github.com/deytenit/ermnvldmr.com-root-commons).
|
||||
|
||||
{{< filetree/container >}}
|
||||
{{< filetree/folder name="configs-repo" state="open" >}}
|
||||
{{< filetree/folder name=".operator" state="open" >}}
|
||||
{{< filetree/folder name="shared" >}}
|
||||
{{< filetree/file name="root (dispatcher)" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< filetree/folder name="local" >}}
|
||||
{{< filetree/file name="node-specific actions" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< filetree/folder name="node-1" >}}
|
||||
{{< filetree/file name="docker-compose.yml" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/container >}}
|
||||
|
||||
---
|
||||
|
||||
**See also:**
|
||||
|
||||
- [Concept: The ROOT_ API](/root/reference/root-api)
|
||||
- [Guide: Installation](/root/guides/installation)
|
||||
- [GitHub: ermnvldmr.com-root-commons](https://github.com/deytenit/ermnvldmr.com-root-commons)
|
||||
@@ -0,0 +1,33 @@
|
||||
---
|
||||
title: Infrastructure principles
|
||||
description: Core principles providing a secure, predictable, and minimal-dependency environment.
|
||||
weight: 5
|
||||
---
|
||||
|
||||
The Root framework is built on core principles designed to provide a secure, predictable, and minimal-dependency environment for independent self-hosted projects.
|
||||
|
||||
## Predictability through structure {#predictability}
|
||||
|
||||
Manual server configuration is prone to "configuration drift," where hosts intended to be identical slowly diverge. Root solves this by:
|
||||
|
||||
- **Git-centric truth**: Every configuration, from UFW rules to crontabs, is stored in the repository.
|
||||
- **Idempotent automation**: [Actions](/root/glossary#action) are designed to be run multiple times without causing side effects, ensuring the host always matches the intended state.
|
||||
|
||||
## Minimal dependency footprint {#minimalism}
|
||||
|
||||
To ensure long-term maintainability, the framework avoids complex configuration management tools (like Ansible or Salt). Instead, it relies on:
|
||||
|
||||
- **Bash**: The universal language of Unix systems.
|
||||
- **Docker**: For application isolation and environment consistency.
|
||||
- **Standard Linux tools**: Leveraging `systemd`, `ufw`, and `cron` directly.
|
||||
|
||||
## Decentralization {#decentralization}
|
||||
|
||||
Each [Node](/root/glossary#node) is an island. While they share the [Commons](/root/glossary#commons) library, they do not depend on a central "master" server. This architecture ensures that a failure in one host does not impact unrelated services.
|
||||
|
||||
---
|
||||
|
||||
**See also:**
|
||||
|
||||
- [Concept: Security model](/root/concepts/security-model)
|
||||
- [Concept: Tiered storage](/root/concepts/tiered-storage)
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Security & privilege isolation
|
||||
description: Security measures, privilege isolation, and project-level sandboxing.
|
||||
weight: 20
|
||||
---
|
||||
|
||||
Security in Root is achieved through strict privilege isolation and project-level "sandboxing" to mitigate the impact of service compromises.
|
||||
|
||||
## The "No-Root" principle {#noroot}
|
||||
|
||||
Running applications as `root` inside containers is a significant security risk. The framework enforces isolation via the `tiers/useradd` and `tiers/chown` actions.
|
||||
|
||||
### Project-specific users
|
||||
|
||||
Every project (e.g., `traefik`, `synapse`) is assigned a dedicated system user on the host.
|
||||
|
||||
- **Isolation**: If a container is compromised, the attacker only gains the privileges of that specific low-privileged user.
|
||||
- **Filesystem safety**: Projects can only read/write to their own directories within the [Tiers](/root/glossary#tier).
|
||||
|
||||
## Docker socket protection {#socket-protection}
|
||||
|
||||
Direct access to `/var/run/docker.sock` is equivalent to root access on the host. To prevent services from abusing this access, the framework utilizes a **Socket Proxy**.
|
||||
|
||||
- **Restricted API**: The proxy filters Docker API calls, allowing only necessary operations (e.g., `GET containers`) and blocking dangerous ones (e.g., `POST containers/create`).
|
||||
|
||||
## Network hardening {#networking}
|
||||
|
||||
Root uses `configure/ufw` to implement a "Default Deny" policy.
|
||||
|
||||
- **Internal routing**: Services communicate over a dedicated `root-direct` bridge network.
|
||||
- **TProxy integration**: Outgoing traffic is routed through Xray for enclave-like isolation and granular routing rules.
|
||||
|
||||
---
|
||||
|
||||
**See also:**
|
||||
|
||||
- [Concept: Tiered storage](/root/concepts/tiered-storage)
|
||||
- [Guide: Action development](/root/guides/action-development)
|
||||
@@ -0,0 +1,48 @@
|
||||
---
|
||||
title: Tiered storage model
|
||||
description: Standardized storage taxonomy for service data.
|
||||
weight: 15
|
||||
---
|
||||
|
||||
The framework enforces a standardized storage taxonomy. This ensures that every service has a predictable location for its data, which simplifies backup strategies and hardware allocation.
|
||||
|
||||
## The storage taxonomy {#taxonomy}
|
||||
|
||||
Data is divided into three logical [Tiers](/root/glossary#tier) based on its lifecycle, volume, and importance.
|
||||
|
||||
### Tier 1: Configuration & critical state
|
||||
|
||||
**Path:** `${ROOT_NODE_DIR}/@tier1`
|
||||
|
||||
- **Contents**: Config files, small SQLite databases, SSL certificates.
|
||||
- **Characteristics**: Extremely high value, low volume.
|
||||
- **Backup strategy**: Frequent (hourly/daily), long retention.
|
||||
|
||||
### Tier 2: Application data
|
||||
|
||||
**Path:** `${ROOT_NODE_DIR}/@tier2`
|
||||
|
||||
- **Contents**: User uploads, large databases, persistent application state.
|
||||
- **Characteristics**: High value, medium to high volume.
|
||||
- **Backup strategy**: Daily, prioritized for integrity.
|
||||
|
||||
### Tier 3: Transients & bulk media
|
||||
|
||||
**Path:** `${ROOT_NODE_DIR}/@tier3`
|
||||
|
||||
- **Contents**: Logs, caches, temporary files, bulk media downloads.
|
||||
- **Characteristics**: Low value, high volume.
|
||||
- **Backup strategy**: Minimal or none. These directories are typically excluded from sync operations.
|
||||
|
||||
## Justification {#justification}
|
||||
|
||||
1. **Backup efficiency**: By separating logs (Tier 3) from configs (Tier 1), we avoid wasting storage space on redundant backups of transient data.
|
||||
2. **Hardware optimization**: Tier 1 and 2 can be placed on fast SSD storage, while Tier 3 can be mounted on slower, high-capacity HDDs.
|
||||
3. **Instant understanding**: Any operator can enter a [Node](/root/glossary#node) directory and immediately know where the critical data resides.
|
||||
|
||||
---
|
||||
|
||||
**See also:**
|
||||
|
||||
- [Concept: Infrastructure architecture](/root/concepts/architecture)
|
||||
- [Reference: ROOT_ API](/root/reference/root-api)
|
||||
Reference in new issue
Block a user