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
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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 %}}
|
||||
@@ -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 <<EOF
|
||||
description: "Brief summary of the task."
|
||||
args:
|
||||
- NODE: "The node name"
|
||||
- PARAM: "A custom parameter"
|
||||
EOF
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3: Initialize context
|
||||
|
||||
Use the `root_require_node` helper to establish the environment. This must be the first functional step in your script.
|
||||
|
||||
```bash filename="scripts/actions/utils/my-action"
|
||||
root_require_node "${1:-}"
|
||||
shift
|
||||
```
|
||||
|
||||
### Step 4: Use namespaced helpers
|
||||
|
||||
Perform operations using the `root_*` library functions. Rely on `ROOT_` environment variables for all pathing.
|
||||
|
||||
```bash filename="scripts/actions/utils/my-action"
|
||||
root_log_info "Processing node $ROOT_NODE"
|
||||
root_sys_restart_service "my-service"
|
||||
```
|
||||
|
||||
{{% /steps %}}
|
||||
|
||||
## Library namespaces {#libraries}
|
||||
|
||||
Actions have access to the following modules:
|
||||
|
||||
- `root_core_*`: Logging and Telegram notifications.
|
||||
- `root_init_*`: Declarative service initialization and package management.
|
||||
- `root_sys_*`: Systemd and unit file management.
|
||||
- `root_template_*`: Envsubst-based rendering and configuration injection.
|
||||
- `root_validate_*`: Input, file, and OS validation.
|
||||
|
||||
---
|
||||
|
||||
**See also:**
|
||||
|
||||
- [Reference: ROOT_ API reference](/root/reference/root-api)
|
||||
- [Concept: Infrastructure architecture](/root/concepts/architecture)
|
||||
@@ -0,0 +1,60 @@
|
||||
---
|
||||
title: Installation
|
||||
description: Initial setup of the Root framework on a new host.
|
||||
weight: 25
|
||||
---
|
||||
|
||||
This guide covers the initial setup of the Root framework on a new host.
|
||||
|
||||
## Prerequisites {#prerequisites}
|
||||
|
||||
- A Debian-based Linux distribution (Debian or Ubuntu).
|
||||
- Git installed.
|
||||
- Sudo privileges.
|
||||
|
||||
## Initializing the repository {#init}
|
||||
|
||||
{{% steps %}}
|
||||
|
||||
### Step 1: Clone the configuration repository
|
||||
|
||||
Clone the repository containing your [Node](/root/glossary#node) configurations.
|
||||
|
||||
```bash
|
||||
git clone <your-configs-repo-url> ~/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 <node_name>
|
||||
root configure/ufw <node_name>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**See also:**
|
||||
|
||||
- [Concept: Infrastructure architecture](/root/concepts/architecture)
|
||||
- [Reference: ROOT_ API reference](/root/reference/root-api)
|
||||
@@ -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 %}}
|
||||
@@ -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 <action> --help`, the dispatcher extracts and displays this YAML-formatted block without executing the script.
|
||||
|
||||
### Example metadata
|
||||
|
||||
```bash filename="example-action-metadata"
|
||||
action_metadata() {
|
||||
cat <<EOF
|
||||
description: "Brief summary of the task."
|
||||
args:
|
||||
- NODE: "The node name"
|
||||
- PARAM: "A custom parameter"
|
||||
EOF
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**See also:**
|
||||
|
||||
- [Concept: Infrastructure principles](/root/concepts/principles)
|
||||
- [Guide: Action development](/root/guides/action-development)
|
||||
Reference in new issue
Block a user