deytenit/ermnvldmr.com
1
0 Fork 0
Code Issues Pull Requests Actions Releases Wiki Activity

docs: Update docs for the correctness (#13)

Browse Source
This commit is contained in:
deytenit authored and GitHub committed 2026-04-15 00:48:06 +03:00
1 parent 8dba55272c
commit 51a783f93a
60 files changed
+2456 -380
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

services/docs/content/en/root/guides/_index.md
+3 -2
View File
@@ -4,9 +4,10 @@ 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.
Step-by-step guides for installing and developing within the ermnvldmr.com root deployment commons framework.
{{% cards %}}
{{< card link="installation" title="Installation" icon="arrow-down" subtitle="Initial setup of the Root framework on a new host." >}}
{{< card link="first-node" title="Setting Up Your First Node" icon="map" subtitle="Practical guide to creating your own config repository." >}}
{{< card link="installation" title="Installation" icon="arrow-down" subtitle="Initial setup of the framework on a new host." >}}
{{< card link="action-development" title="Action development" icon="code" subtitle="Creating and managing atomic automation tasks." >}}
{{% /cards %}}
services/docs/content/en/root/guides/first-node.md
+190
View File
@@ -0,0 +1,190 @@
---
title: "Setting Up Your First Node"
description: A practical guide on creating your first node and hooking up the deployment commons.
weight: 25
---
**Goal:** Create a configuration repository for your infrastructure, add the root deployment commons as a submodule, and define your first basic node.
## 1. Creating the Configuration Repository
Your infrastructure should be managed from a single Git repository. This repository will hold the configuration for all your servers (nodes).
{{% steps %}}
### Step 1: Initialize the repository
Create a new directory and initialize Git.
```bash
mkdir my-infrastructure
cd my-infrastructure
git init
```
### Step 2: Add the commons submodule
The `ermnvldmr.com-root-commons` must be placed at `.operator/shared`.
```bash
mkdir -p .operator
git submodule add https://github.com/deytenit/ermnvldmr.com-root-commons.git .operator/shared
```
### Step 3: Create the Bootstrap Script
Create an `init.sh` file at the root of your repository. This script links the commons framework into your local environment.
```bash filename="init.sh"
#!/usr/bin/env bash
# init.sh
# Source common utilities from the submodule
source "$(git -C "$(dirname "$0")" rev-parse --show-toplevel)/.operator/shared/scripts/lib/common.sh"
SCRIPT_NAME="init"
navigate_to_repo_root
log_info "Setting up Git hooks..."
git config core.hooksPath .operator/shared/githooks
git config --global --add safe.directory "${REPO_ROOT}"
log_info "Setting up PATH for the root dispatcher..."
ABSOLUTE_RUN_DIR="$(realpath "${REPO_ROOT}/.operator/shared/scripts/run")"
BASHRC_ENTRY="export PATH=\"${ABSOLUTE_RUN_DIR}:\$PATH\""
sed -i '/\.operator\/shared\/scripts\/run/d' ~/.bashrc
echo "$BASHRC_ENTRY" >> ~/.bashrc
log_info "Done. Please run 'source ~/.bashrc' or re-login to your shell."
```
Make it executable:
```bash
chmod +x init.sh
```
{{% /steps %}}
## 2. Defining Your First Node
A Node is a folder at the repository root that represents one physical or virtual server.
### Node Structure
Let's create a node named `daedalus`. Inside, we'll define an operator configuration (e.g., for backups) and a core service.
```bash
mkdir -p daedalus/.operator/configs/{cron,crowdsec,systemd,ufw/docker,ufw/host}
mkdir -p daedalus/root
```
### Base Configurations (Optional)
You can place configuration files (like UFW rules or a crontab) inside the `daedalus/.operator/configs/` directory. For example, a basic crontab:
```bash filename="daedalus/.operator/configs/cron/crontab.template"
# Run backups every night at 3:00 AM
0 3 * * * root sync tiers daedalus
```
## 3. Configuring Services (Docker Compose)
The framework relies on `docker-compose.yml` to orchestrate services.
### Node-Level Infrastructure (Operator)
The `daedalus/docker-compose.yml` file runs infrastructure utilities, such as `restic` for backups or VPN agents. This compose file has direct access to the filesystem via `@tierX` mounts.
```yaml filename="daedalus/docker-compose.yml"
name: 'operator'
services:
restic:
image: restic/restic:0.18.1
container_name: operator-restic
volumes:
# Example: mounting project data for backups (Read-Only)
- ./@tier2/my-app/data:/data/@tier2/my-app/data:ro
- ./@tier3/.operator/restic/cache:/var/restic-cache
environment:
RESTIC_REPOSITORY: "s3:example.com/my-bucket/daedalus"
RESTIC_PASSWORD: "${RESTIC_PASSWORD?error}"
# AWS credentials...
network_mode: "host"
entrypoint: [ "restic" ]
```
### The Root Project
The `root` project typically contains your reverse proxies (Traefik) and core services that other projects will route through.
```yaml filename="daedalus/root/docker-compose.yml"
name: root
services:
socket-proxy:
image: tecnativa/docker-socket-proxy:0
container_name: root-socket-proxy
user: "0:0"
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
environment:
CONTAINERS: 1
SERVICES: 1
TASKS: 1
networks:
socket: {}
restart: unless-stopped
traefik:
image: traefik:3.6
container_name: root-traefik
# UID and GID are automatically populated by the framework after running 'root tiers useradd'
user: "${UID?error}:${GID?error}"
group_add:
- "${SHARED_GID?error}"
depends_on:
- socket-proxy
volumes:
- ./@tier1/shared/root/traefik/letsencrypt:/letsencrypt
- ./@tier3/traefik/logs:/logs
- ./@tier1/traefik/dynamic:/etc/traefik/dynamic:ro
ports:
- '0.0.0.0:80:80'
- '0.0.0.0:443:443'
networks:
proxy: {}
socket: {}
command:
- "--api.dashboard=true"
- "--providers.docker=true"
- "--providers.docker.network=root-proxy"
- "--providers.docker.endpoint=tcp://root-socket-proxy:2375"
restart: unless-stopped
networks:
proxy:
name: root-proxy
internal: true
driver: bridge
socket:
name: root-socket
internal: true
driver: bridge
```
## 4. Deployment
Now that your structure is ready:
1. Commit and push this repository to your Git server (e.g., GitHub).
2. SSH into your VPS.
3. Follow the [Installation](/root/guides/installation) guide, using your new repository URL instead of the example ones.
---
**See also:**
- [Guide: Installation on a new host](/root/guides/installation)
- [Concept: Infrastructure Architecture](/root/concepts/architecture)
services/docs/content/en/root/guides/installation.md
+171 -32
View File
@@ -1,60 +1,199 @@
---
title: Installation
description: Initial setup of the Root framework on a new host.
weight: 25
title: Initial Host Setup
description: Setting up a fresh Debian host from scratch.
weight: 1
---
This guide covers the initial setup of the Root framework on a new host.
Hardened setup for a fresh Debian host from zero to deployment.
## Prerequisites {#prerequisites}
- A Debian-based Linux distribution (Debian or Ubuntu).
- Git installed.
- Sudo privileges.
## Initializing the repository {#init}
## Setup Procedure
{{% steps %}}
### Step 1: Clone the configuration repository
### Essential Packages
Clone the repository containing your [Node](/root/glossary#node) configurations.
Install `sudo` and `docker-ce` first. This is necessary because the subsequent user setup relies on the `docker` group and `sudo` configuration.
**Install Sudo**
```bash
git clone <your-configs-repo-url> ~/repo
cd ~/repo
# As root:
apt update && apt install sudo -y
```
### Step 2: Run the initialization script
**Install Docker**
The `init.sh` script sets up the [Commons](/root/glossary#commons) submodule, configures Git hooks, and adds the `root` wrapper to your `PATH`.
Follow the [Official Docker Installation Guide for Debian](https://docs.docker.com/engine/install/debian/) to install the latest Docker Engine.
### System User & Privileges
The `adam` user handles all administrative tasks. SSH-key authentication and passwordless `sudo` via the `wheel` group minimize friction while maintaining security.
**Create the Admin User**
```bash
./init.sh
# As root:
# Create the user with a bash shell
useradd -m -s /bin/bash adam
# Create the wheel group (common for cross-distro consistency)
groupadd wheel
# Create a modular sudoers file
# This allows members of 'wheel' to run sudo without a password
echo "%wheel ALL=(ALL) NOPASSWD: ALL" > /etc/sudoers.d/99-custom-sudoers
# Validate syntax
visudo -c -f /etc/sudoers.d/99-custom-sudoers
# Add adam to the necessary groups
usermod -aG wheel,docker adam
```
### Step 3: Refresh your shell
### Swap Setup
Source your `.bashrc` to activate the `root` command.
Configure a swap file to ensure system stability during memory-intensive operations.
```bash
source ~/.bashrc
# As root:
# Create a 2GB swap file (adjust size as needed)
fallocate -l 2G /swap
chmod 600 /swap
mkswap /swap
swapon /swap
# Make it permanent
echo '/swap none swap sw 0 0' >> /etc/fstab
```
### SSH Access & Hardening
Passwords are disabled. Access is strictly via SSH keys.
**Authorize Operator Key**
Import your local public key to the `adam` user.
```bash
# As root:
# Setup directories
mkdir -p /home/adam/.ssh
chmod 700 /home/adam/.ssh
# Add your public key (Replace [PASTE_PUB_KEY_HERE])
echo "[PASTE_PUB_KEY_HERE]" > /home/adam/.ssh/authorized_keys
chmod 600 /home/adam/.ssh/authorized_keys
chown -R adam:adam /home/adam/.ssh
```
**Operator Side Access**
Configure your local machine for easy access to the host.
```bash
# ~/.ssh/config on operator side
Host daedalus.example.com
Port 2222
User adam
IdentityFile ~/.ssh/adam_example_com_ed25519
```
**Harden SSH Daemon**
Modify the SSH configuration to change the default port and disable password entry.
```bash
# As root:
# Create a dedicated override config
cat <<EOF > /etc/ssh/sshd_config.d/99-custom-ssh.conf
Port 2222
PasswordAuthentication no
PermitEmptyPasswords no
AllowUsers adam
EOF
# Validate syntax before restarting to avoid lockout
sshd -t && systemctl restart ssh
```
### GitHub Access (Deploy Key)
The host requires its own identity to pull updates from the GitHub repository.
```bash
# As root:
# Generate a host-specific SSH key (no passphrase for automation)
sudo -u adam ssh-keygen -t ed25519 -f /home/adam/.ssh/github_ed25519 -N ""
# Configure SSH to use this key for GitHub
cat <<EOF | sudo -u adam tee /home/adam/.ssh/config
Host github.com
AddKeysToAgent yes
IdentityFile ~/.ssh/github_ed25519
EOF
# Display the public key to be added to GitHub (Settings > Deploy Keys)
cat /home/adam/.ssh/github_ed25519.pub
```
> [!TIP]
> Add the output above to the Deploy Keys settings of your infrastructure repository (e.g., `https://github.com/your-username/your-repo/settings/keys`) with **read access**.
### Repository Deployment
Clone your infrastructure repository and initialize the node.
```bash
# As root:
# Setup the service directory
export REPO_DIR="/srv/your-infrastructure-repo"
mkdir -p $REPO_DIR
chown adam:adam $REPO_DIR
# Clone as the adam user
sudo -u adam git clone git@github.com:your-username/your-repo.git $REPO_DIR
# Initialize node (Set your node name, e.g., daedalus)
export NODE="daedalus"
cd $REPO_DIR
sudo -u adam ./init.sh
```
**Node-Specific Configuration**
Run the staged initialization scripts using the `root` dispatcher:
```bash
# Run the sequence for your specific node (as the 'adam' user)
# Ensure you have sourced ~/.bashrc or re-logged in if 'root' is not found
root configure base $NODE
root configure ufw $NODE
root configure crowdsec $NODE
root configure cron $NODE
```
### Storage & Hardening
Define the data tiers and secure the environment by creating non-root users for containerized services.
```bash
# Create (or mount) storage directories
sudo mkdir -p /srv/my-infrastructure-root-$NODE-{tier1,tier2,tier3}
# Setup tiers and non-root users
root tiers link $NODE \
/srv/my-infrastructure-root-$NODE-tier1 \
/srv/my-infrastructure-root-$NODE-tier2 \
/srv/my-infrastructure-root-$NODE-tier3
root tiers useradd $NODE
root tiers chown $NODE
```
{{% /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)
- [Doc: Docker - Install on Debian](https://docs.docker.com/engine/install/debian/)