diff --git a/services/docs/content/en/root/_index.md b/services/docs/content/en/root/_index.md index 4807c08..8bede56 100644 --- a/services/docs/content/en/root/_index.md +++ b/services/docs/content/en/root/_index.md @@ -1,22 +1,35 @@ --- -title: 'Root Infrastructure' -description: 'Documentation for the root.ermnvldmr.com infrastructure.' +title: Root Infrastructure +description: Documentation for the root.ermnvldmr.com infrastructure. weight: 1 type: docs cascade: type: docs --- -Comprehensive documentation for the personal infrastructure deployment and management, including setup guides and operational recipes. +The engine powering the shared infrastructure of `root.ermnvldmr.com`. This framework provides a minimal-dependency deployment environment for independent, self-hosted projects. + +The generic logic, scripts, and deployment patterns used across multiple unrelated self-hosted applications are stored in the [GitHub: ermnvldmr.com-root-commons](https://github.com/deytenit/ermnvldmr.com-root-commons) repository. + +## Core features + +- **Smart Dispatcher**: A single entrypoint (`root`) for all orchestration tasks. +- **Tiered Storage**: Standardized classification for configuration, data, and logs. +- **Privilege Isolation**: Project-specific non-root users for enhanced security. +- **Namespaced Libraries**: Explicit, modular Bash utilities for consistent automation. ## Sections {{% cards %}} +{{< card link="concepts" title="Concepts" icon="book-open" subtitle="Theoretical foundations, architecture, and security models." >}} +{{< card link="guides" title="Guides" icon="map" subtitle="Step-by-step guides for installation and action development." >}} {{< card link="recipes" title="Recipes" icon="beaker" subtitle="Collection of step-by-step procedures for infrastructure maintenance and deployment." >}} +{{< card link="reference" title="Reference" icon="code" subtitle="API and technical references for developers." >}} {{% /cards %}} --- **See also:** +- [GitHub: ermnvldmr.com-root-commons](https://github.com/deytenit/ermnvldmr.com-root-commons) - [GitHub: root.ermnvldmr.com](https://github.com/deytenit/root.ermnvldmr.com) diff --git a/services/docs/content/en/root/concepts/_index.md b/services/docs/content/en/root/concepts/_index.md new file mode 100644 index 0000000..2a17d04 --- /dev/null +++ b/services/docs/content/en/root/concepts/_index.md @@ -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 %}} diff --git a/services/docs/content/en/root/concepts/architecture.md b/services/docs/content/en/root/concepts/architecture.md new file mode 100644 index 0000000..ae7bf3a --- /dev/null +++ b/services/docs/content/en/root/concepts/architecture.md @@ -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) diff --git a/services/docs/content/en/root/concepts/principles.md b/services/docs/content/en/root/concepts/principles.md new file mode 100644 index 0000000..cf45429 --- /dev/null +++ b/services/docs/content/en/root/concepts/principles.md @@ -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) diff --git a/services/docs/content/en/root/concepts/security-model.md b/services/docs/content/en/root/concepts/security-model.md new file mode 100644 index 0000000..907668d --- /dev/null +++ b/services/docs/content/en/root/concepts/security-model.md @@ -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) diff --git a/services/docs/content/en/root/concepts/tiered-storage.md b/services/docs/content/en/root/concepts/tiered-storage.md new file mode 100644 index 0000000..ea194b1 --- /dev/null +++ b/services/docs/content/en/root/concepts/tiered-storage.md @@ -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) diff --git a/services/docs/content/en/root/glossary.md b/services/docs/content/en/root/glossary.md new file mode 100644 index 0000000..24a7a77 --- /dev/null +++ b/services/docs/content/en/root/glossary.md @@ -0,0 +1,41 @@ +--- +title: Glossary +description: Terminology used within the Root infrastructure framework. +weight: 100 +--- + +Terminology used within the Root infrastructure framework. + +## Action {#action} + +**Action** - An atomic automation task located in `scripts/actions/`. Actions follow the "Stupid Action" philosophy, remaining declarative and relying on the `root` dispatcher for environment setup. + +## Commons {#commons} + +**Commons** - The shared repository containing generic logic, namespaced libraries, and standardized automation actions used across all nodes. Referenced at [GitHub: ermnvldmr.com-root-commons](https://github.com/deytenit/ermnvldmr.com-root-commons). + +## Dispatcher {#dispatcher} + +**Dispatcher** - The `root` script that serves as the entrypoint. It resolves paths, warms the environment, and executes the requested [Action](/root/glossary#action). + +## Node {#node} + +**Node** - A physical or virtual host managed by the framework. Each node has a dedicated directory in the configuration repository containing its services and local settings. + +## Root {#root} + +**Root** - Both the name of the command-line utility and the top-level orchestration service within a [Node](/root/glossary#node) (typically handling Traefik and Adguard). + +## Tier {#tier} + +**Tier** - A standardized storage classification for service data. +- **Tier 1**: Configuration and critical state. +- **Tier 2**: Application data and databases. +- **Tier 3**: Logs, caches, and bulk media. + +--- + +**See also:** + +- [Concept: Infrastructure architecture](/root/concepts/architecture) +- [Concept: Tiered storage model](/root/concepts/tiered-storage) diff --git a/services/docs/content/en/root/guides/_index.md b/services/docs/content/en/root/guides/_index.md new file mode 100644 index 0000000..3b60a0a --- /dev/null +++ b/services/docs/content/en/root/guides/_index.md @@ -0,0 +1,12 @@ +--- +title: Guides +description: Step-by-step guides for installation and action development. +weight: 20 +--- + +Step-by-step guides for installing and developing within the Root infrastructure framework. + +{{% cards %}} +{{< card link="installation" title="Installation" icon="arrow-down" subtitle="Initial setup of the Root framework on a new host." >}} +{{< card link="action-development" title="Action development" icon="code" subtitle="Creating and managing atomic automation tasks." >}} +{{% /cards %}} diff --git a/services/docs/content/en/root/guides/action-development.md b/services/docs/content/en/root/guides/action-development.md new file mode 100644 index 0000000..246f18c --- /dev/null +++ b/services/docs/content/en/root/guides/action-development.md @@ -0,0 +1,67 @@ +--- +title: Action development +description: Developing atomic automation tasks in the Root framework. +weight: 30 +--- + +[Actions](/root/glossary#action) are atomic automation tasks. Following the "Stupid Action" philosophy, they must remain declarative and rely on the library for complex operations. + +## Creating a new action {#create} + +{{% steps %}} + +### Step 1: Create the script file + +Place your script in `scripts/actions/{group}/{name}`. Do not use file extensions. + +### Step 2: Implement metadata + +Every action must provide a description and argument list for the help system. + +```bash filename="scripts/actions/utils/my-action" +action_metadata() { + cat < ~/repo +cd ~/repo +``` + +### Step 2: Run the initialization script + +The `init.sh` script sets up the [Commons](/root/glossary#commons) submodule, configures Git hooks, and adds the `root` wrapper to your `PATH`. + +```bash +./init.sh +``` + +### Step 3: Refresh your shell + +Source your `.bashrc` to activate the `root` command. + +```bash +source ~/.bashrc +``` + +{{% /steps %}} + +## Provisioning a node {#provision} + +Once the framework is installed, you can provision a specific [Node](/root/glossary#node). + +```bash +root configure/base +root configure/ufw +``` + +--- + +**See also:** + +- [Concept: Infrastructure architecture](/root/concepts/architecture) +- [Reference: ROOT_ API reference](/root/reference/root-api) diff --git a/services/docs/content/en/root/reference/_index.md b/services/docs/content/en/root/reference/_index.md new file mode 100644 index 0000000..435c576 --- /dev/null +++ b/services/docs/content/en/root/reference/_index.md @@ -0,0 +1,11 @@ +--- +title: Reference +description: API and technical references for developers. +weight: 30 +--- + +Technical reference materials and APIs for the Root framework. + +{{% cards %}} +{{< card link="root-api" title="ROOT_ API reference" icon="code" subtitle="Standardized environment variables and logging helpers." >}} +{{% /cards %}} diff --git a/services/docs/content/en/root/reference/root-api.md b/services/docs/content/en/root/reference/root-api.md new file mode 100644 index 0000000..f465c42 --- /dev/null +++ b/services/docs/content/en/root/reference/root-api.md @@ -0,0 +1,66 @@ +--- +title: ROOT_ API reference +description: Standardized environment variables for path resolution and node context. +weight: 50 +--- + +Every [Action](/root/glossary#action) script executed via the `root` dispatcher has access to a standardized set of environment variables. These variables are the single source of truth for path resolution and node context. + +## Path resolution variables {#paths} + +These variables define the physical location of the infrastructure components. + +| Variable | Description | +| :--- | :--- | +| `ROOT_SHARED` | Absolute path to the [Commons](/root/glossary#commons) repository. | +| `ROOT_CONFIGS` | Absolute path to the main configuration repository. | +| `ROOT_LOCAL` | Absolute path to the local operator directory (`.operator/local`). | +| `ROOT_ACTIONS_SHARED` | Path to the global shared actions. | +| `ROOT_ACTIONS_LOCAL` | Path to node-specific local actions. | + +## Node context variables {#node-context} + +When an action targets a specific [Node](/root/glossary#node), the following variables are established by the `root_require_node` helper. + +| Variable | Description | +| :--- | :--- | +| `ROOT_NODE` | The identifier of the target node (e.g., `icarus`). | +| `ROOT_NODE_DIR` | Absolute path to the node configuration directory. | +| `ROOT_TIER1` | Absolute path to the [Tier 1](/root/glossary#tier) storage directory. | +| `ROOT_TIER2` | Absolute path to the Tier 2 storage directory. | +| `ROOT_TIER3` | Absolute path to the Tier 3 storage directory. | + +## Logging helpers {#logging} + +Standardized logging uses the `[$ROOT_NODE] [$ROOT_ACTION_PATH]` prefix for consistency across the orchestration logs. + +- `root_log_info`: Standard informational output. +- `root_log_warn`: Warnings requiring attention but not stopping execution. +- `root_log_error`: Critical errors sent to `stderr`. +- `root_log_success`: Confirmation of successful task completion. + +## Help system metadata {#help} + +The `root` [Dispatcher](/root/glossary#dispatcher) provides a built-in `--help` system. To keep action scripts "stupid", they do not implement their own help flags. Instead, the dispatcher parses a specific `action_metadata` block defined at the top of every action script. + +When a user runs `root --help`, the dispatcher extracts and displays this YAML-formatted block without executing the script. + +### Example metadata + +```bash filename="example-action-metadata" +action_metadata() { + cat <