docs: Update docs for the correctness (#13)
This commit is contained in:
deytenit authored and 
GitHub committed
1 parent
8dba55272c
commit
51a783f93a
60 files changed
+2456
-380
No files matched your search
@@ -0,0 +1,13 @@
|
||||
---
|
||||
title: Руководства
|
||||
description: Пошаговые инструкции по установке и разработке Action-скриптов.
|
||||
weight: 20
|
||||
---
|
||||
|
||||
Пошаговые инструкции по установке и разработке в рамках общих модулей корневой инфраструктуры ermnvldmr.com.
|
||||
|
||||
{{% cards %}}
|
||||
{{< card link="first-node" title="Создание вашего первого узла" icon="map" subtitle="Практическое руководство по созданию репозитория конфигураций." >}}
|
||||
{{< card link="installation" title="Установка" icon="arrow-down" subtitle="Первоначальная настройка общих модулей на новом хосте." >}}
|
||||
{{< card link="action-development" title="Разработка Action-скриптов" icon="code" subtitle="Создание и управление атомарными задачами автоматизации." >}}
|
||||
{{% /cards %}}
|
||||
@@ -0,0 +1,67 @@
|
||||
---
|
||||
title: Разработка Action-скриптов
|
||||
description: Разработка атомарных задач автоматизации в рамках общих модулей.
|
||||
weight: 30
|
||||
---
|
||||
|
||||
[Action-скрипты](/root/glossary#action) — это атомарные задачи автоматизации. Следуя философии "Stupid Action" («Глупое действие»), они должны оставаться декларативными и полагаться на библиотеку для выполнения сложных операций.
|
||||
|
||||
## Создание нового Action-скрипта {#create}
|
||||
|
||||
{{% steps %}}
|
||||
|
||||
### Шаг 1: Создание файла скрипта
|
||||
|
||||
Поместите ваш скрипт в `scripts/actions/{group}/{name}`. Не используйте расширения файлов.
|
||||
|
||||
### Шаг 2: Реализация метаданных
|
||||
|
||||
Каждый Action-скрипт должен предоставлять описание и список аргументов для системы справки (help system).
|
||||
|
||||
```bash filename="scripts/actions/utils/my-action"
|
||||
action_metadata() {
|
||||
cat <<EOF
|
||||
description: "Краткое описание задачи."
|
||||
args:
|
||||
- NODE: "Имя узла"
|
||||
- PARAM: "Пользовательский параметр"
|
||||
EOF
|
||||
}
|
||||
```
|
||||
|
||||
### Шаг 3: Инициализация контекста
|
||||
|
||||
Используйте вспомогательную функцию `root_require_node` для настройки окружения. Это должно быть первым функциональным шагом в вашем скрипте.
|
||||
|
||||
```bash filename="scripts/actions/utils/my-action"
|
||||
root_require_node "${1:-}"
|
||||
shift
|
||||
```
|
||||
|
||||
### Шаг 4: Использование модульных функций
|
||||
|
||||
Выполняйте операции, используя библиотечные функции `root_*`. Полагайтесь на переменные окружения `ROOT_` для всех путей.
|
||||
|
||||
```bash filename="scripts/actions/utils/my-action"
|
||||
root_log_info "Обработка узла $ROOT_NODE"
|
||||
root_sys_restart_service "my-service"
|
||||
```
|
||||
|
||||
{{% /steps %}}
|
||||
|
||||
## Пространства имен библиотек {#libraries}
|
||||
|
||||
Action-скрипты имеют доступ к следующим модулям:
|
||||
|
||||
- `root_core_*`: Логирование и уведомления в Telegram.
|
||||
- `root_init_*`: Декларативная инициализация сервисов и управление пакетами.
|
||||
- `root_sys_*`: Управление systemd и файлами юнитов.
|
||||
- `root_template_*`: Рендеринг на основе envsubst и внедрение конфигураций.
|
||||
- `root_validate_*`: Проверка ввода, файлов и ОС.
|
||||
|
||||
---
|
||||
|
||||
**См. также:**
|
||||
|
||||
- [Справочник: Справочник ROOT_ API](/root/reference/root-api)
|
||||
- [Концепция: Архитектура инфраструктуры](/root/concepts/architecture)
|
||||
@@ -0,0 +1,190 @@
|
||||
---
|
||||
title: "Создание узла (First Node)"
|
||||
description: Практическое руководство по созданию вашего первого узла и подключению общих модулей.
|
||||
weight: 25
|
||||
---
|
||||
|
||||
**Цель:** Создать репозиторий конфигураций для вашей собственной инфраструктуры, подключить общие модули в качестве подмодуля (submodule) и запустить первый базовый узел.
|
||||
|
||||
## 1. Создание репозитория конфигураций
|
||||
|
||||
Ваша инфраструктура должна управляться из единого Git-репозитория. Этот репозиторий будет содержать конфигурации для всех ваших серверов (узлов).
|
||||
|
||||
{{% steps %}}
|
||||
|
||||
### Шаг 1: Инициализация репозитория
|
||||
|
||||
Создайте новую директорию и инициализируйте Git.
|
||||
|
||||
```bash
|
||||
mkdir my-infrastructure
|
||||
cd my-infrastructure
|
||||
git init
|
||||
```
|
||||
|
||||
### Шаг 2: Добавление общих модулей как подмодуля
|
||||
|
||||
Общие модули (`ermnvldmr.com-root-commons`) должны располагаться по пути `.operator/shared`.
|
||||
|
||||
```bash
|
||||
mkdir -p .operator
|
||||
git submodule add https://github.com/deytenit/ermnvldmr.com-root-commons.git .operator/shared
|
||||
```
|
||||
|
||||
### Шаг 3: Создание загрузочного скрипта (Bootstrap)
|
||||
|
||||
Создайте файл `init.sh` в корне вашего репозитория. Этот скрипт свяжет общие модули с вашим локальным окружением.
|
||||
|
||||
```bash filename="init.sh"
|
||||
#!/usr/bin/env bash
|
||||
# init.sh
|
||||
|
||||
# Загрузка общих утилит из подмодуля
|
||||
source "$(git -C "$(dirname "$0")" rev-parse --show-toplevel)/.operator/shared/scripts/lib/common.sh"
|
||||
|
||||
SCRIPT_NAME="init"
|
||||
|
||||
navigate_to_repo_root
|
||||
|
||||
log_info "Настройка Git hooks..."
|
||||
git config core.hooksPath .operator/shared/githooks
|
||||
git config --global --add safe.directory "${REPO_ROOT}"
|
||||
|
||||
log_info "Настройка PATH для диспетчера root..."
|
||||
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 "Готово. Выполните 'source ~/.bashrc' или перезайдите в терминал."
|
||||
```
|
||||
|
||||
Сделайте его исполняемым:
|
||||
```bash
|
||||
chmod +x init.sh
|
||||
```
|
||||
|
||||
{{% /steps %}}
|
||||
|
||||
## 2. Определение вашего первого узла
|
||||
|
||||
Узел (Node) — это папка в корне репозитория, которая представляет один физический или виртуальный сервер.
|
||||
|
||||
### Структура узла
|
||||
|
||||
Давайте создадим узел с именем `daedalus`. Внутри него мы определим конфигурацию оператора (например, для резервного копирования) и базовый сервис.
|
||||
|
||||
```bash
|
||||
mkdir -p daedalus/.operator/configs/{cron,crowdsec,systemd,ufw/docker,ufw/host}
|
||||
mkdir -p daedalus/root
|
||||
```
|
||||
|
||||
### Базовые настройки (Опционально)
|
||||
|
||||
Вы можете добавить файлы конфигурации (например, правила UFW или crontab) в директорию `daedalus/.operator/configs/`. Например, простой crontab:
|
||||
|
||||
```bash filename="daedalus/.operator/configs/cron/crontab.template"
|
||||
# Запуск резервного копирования каждую ночь в 3:00
|
||||
0 3 * * * root sync tiers daedalus
|
||||
```
|
||||
|
||||
## 3. Настройка сервисов (Docker Compose)
|
||||
|
||||
Фреймворк опирается на `docker-compose.yml`.
|
||||
|
||||
### Инфраструктурный уровень (Узел оператора)
|
||||
|
||||
Файл `daedalus/docker-compose.yml` запускает инфраструктурные утилиты, такие как `restic` для бекапов или VPN-агенты. Этот compose-файл имеет прямой доступ к файловой системе через монтирование директорий `@tierX`.
|
||||
|
||||
```yaml filename="daedalus/docker-compose.yml"
|
||||
name: 'operator'
|
||||
|
||||
services:
|
||||
restic:
|
||||
image: restic/restic:0.18.1
|
||||
container_name: operator-restic
|
||||
volumes:
|
||||
# Пример: монтирование данных для резервного копирования (Только для чтения)
|
||||
- ./@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...
|
||||
network_mode: "host"
|
||||
entrypoint: [ "restic" ]
|
||||
```
|
||||
|
||||
### Корневой уровень (Root)
|
||||
|
||||
Проект `root` обычно содержит обратные прокси (Traefik) и сервисы, к которым обращаются другие проекты.
|
||||
|
||||
```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 и GID подставляются автоматически фреймворком после команды '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. Развертывание
|
||||
|
||||
Теперь, когда структура создана:
|
||||
|
||||
1. Закоммитьте и отправьте (push) этот репозиторий на ваш Git-сервер (например, GitHub).
|
||||
2. Зайдите на ваш VPS.
|
||||
3. Следуйте руководству по [Установке (Installation)](/root/guides/installation), используя URL вашего нового репозитория.
|
||||
|
||||
---
|
||||
|
||||
**См. также:**
|
||||
|
||||
- [Руководство: Установка на новый хост](/root/guides/installation)
|
||||
- [Концепция: Архитектура инфраструктуры](/root/concepts/architecture)
|
||||
@@ -0,0 +1,199 @@
|
||||
---
|
||||
title: 'Начальная настройка хоста'
|
||||
description: 'Настройка чистого хоста Debian с нуля.'
|
||||
weight: 1
|
||||
---
|
||||
|
||||
Защищенная настройка чистого хоста Debian от нуля до развертывания.
|
||||
|
||||
## Процедура настройки
|
||||
|
||||
{{% steps %}}
|
||||
|
||||
### Основные пакеты
|
||||
|
||||
Сначала установите `sudo` и `docker-ce`. Это необходимо, так как последующая настройка пользователя опирается на группу `docker` и конфигурацию `sudo`.
|
||||
|
||||
**Установка Sudo**
|
||||
|
||||
```bash
|
||||
# От имени root:
|
||||
apt update && apt install sudo -y
|
||||
```
|
||||
|
||||
**Установка Docker**
|
||||
|
||||
Следуйте [официальному руководству по установке Docker для Debian](https://docs.docker.com/engine/install/debian/), чтобы установить последнюю версию Docker Engine.
|
||||
|
||||
### Системный пользователь и привилегии
|
||||
|
||||
Пользователь `adam` выполняет все административные задачи. Аутентификация по SSH-ключу и беспарольный `sudo` через группу `wheel` минимизируют трение при сохранении безопасности.
|
||||
|
||||
**Создание администратора**
|
||||
|
||||
```bash
|
||||
# От имени root:
|
||||
# Создать пользователя с оболочкой bash
|
||||
useradd -m -s /bin/bash adam
|
||||
|
||||
# Создать группу wheel (общепринято для единообразия между дистрибутивами)
|
||||
groupadd wheel
|
||||
|
||||
# Создать модульный файл sudoers
|
||||
# Это позволяет членам группы 'wheel' запускать sudo без пароля
|
||||
echo "%wheel ALL=(ALL) NOPASSWD: ALL" > /etc/sudoers.d/99-custom-sudoers
|
||||
|
||||
# Проверить синтаксис
|
||||
visudo -c -f /etc/sudoers.d/99-custom-sudoers
|
||||
|
||||
# Добавить adam в необходимые группы
|
||||
usermod -aG wheel,docker adam
|
||||
```
|
||||
|
||||
### Настройка Swap
|
||||
|
||||
Настройте файл подкачки (swap), чтобы обеспечить стабильность системы во время операций, требующих большого объема памяти.
|
||||
|
||||
```bash
|
||||
# От имени root:
|
||||
# Создать файл подкачки размером 2 ГБ (измените размер при необходимости)
|
||||
fallocate -l 2G /swap
|
||||
chmod 600 /swap
|
||||
mkswap /swap
|
||||
swapon /swap
|
||||
|
||||
# Сделать его постоянным
|
||||
echo '/swap none swap sw 0 0' >> /etc/fstab
|
||||
```
|
||||
|
||||
### SSH Доступ и Усиление
|
||||
|
||||
Пароли отключены. Доступ осуществляется строго по SSH-ключам.
|
||||
|
||||
**Авторизация ключа оператора**
|
||||
|
||||
Импортируйте ваш локальный публичный ключ для пользователя `adam`.
|
||||
|
||||
```bash
|
||||
# От имени root:
|
||||
# Настроить директории
|
||||
mkdir -p /home/adam/.ssh
|
||||
chmod 700 /home/adam/.ssh
|
||||
|
||||
# Добавьте свой публичный ключ (Замените [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
|
||||
```
|
||||
|
||||
**Доступ со стороны оператора**
|
||||
|
||||
Настройте вашу локальную машину для удобного доступа к хосту.
|
||||
|
||||
```bash
|
||||
# ~/.ssh/config на стороне оператора
|
||||
Host daedalus.example.com
|
||||
Port 2222
|
||||
User adam
|
||||
IdentityFile ~/.ssh/adam_example_com_ed25519
|
||||
```
|
||||
|
||||
**Усиление демона SSH**
|
||||
|
||||
Измените конфигурацию SSH, чтобы сменить порт по умолчанию и отключить вход по паролю.
|
||||
|
||||
```bash
|
||||
# От имени root:
|
||||
# Создать выделенный файл конфигурации
|
||||
cat <<EOF > /etc/ssh/sshd_config.d/99-custom-ssh.conf
|
||||
Port 2222
|
||||
PasswordAuthentication no
|
||||
PermitEmptyPasswords no
|
||||
AllowUsers adam
|
||||
EOF
|
||||
|
||||
# Проверить синтаксис перед перезапуском, чтобы избежать блокировки
|
||||
sshd -t && systemctl restart ssh
|
||||
```
|
||||
|
||||
### Доступ к GitHub (Deploy Key)
|
||||
|
||||
Хосту требуется собственная идентификация для загрузки обновлений из репозитория GitHub.
|
||||
|
||||
```bash
|
||||
# От имени root:
|
||||
# Сгенерировать специфичный для хоста SSH-ключ (без парольной фразы для автоматизации)
|
||||
sudo -u adam ssh-keygen -t ed25519 -f /home/adam/.ssh/github_ed25519 -N ""
|
||||
|
||||
# Настроить SSH для использования этого ключа для GitHub
|
||||
cat <<EOF | sudo -u adam tee /home/adam/.ssh/config
|
||||
Host github.com
|
||||
AddKeysToAgent yes
|
||||
IdentityFile ~/.ssh/github_ed25519
|
||||
EOF
|
||||
|
||||
# Отобразить публичный ключ для добавления в GitHub (Settings > Deploy Keys)
|
||||
cat /home/adam/.ssh/github_ed25519.pub
|
||||
```
|
||||
|
||||
> [!TIP]
|
||||
> Добавьте вывод выше в настройки Deploy Keys вашего репозитория инфраструктуры (например, `https://github.com/your-username/your-repo/settings/keys`) с правами **read access**.
|
||||
|
||||
### Развертывание репозитория
|
||||
|
||||
Клонируйте репозиторий вашей инфраструктуры и инициализируйте узел.
|
||||
|
||||
```bash
|
||||
# От имени root:
|
||||
# Настройка директории сервиса
|
||||
export REPO_DIR="/srv/your-infrastructure-repo"
|
||||
mkdir -p $REPO_DIR
|
||||
chown adam:adam $REPO_DIR
|
||||
|
||||
# Клонирование от имени пользователя adam
|
||||
sudo -u adam git clone git@github.com:your-username/your-repo.git $REPO_DIR
|
||||
|
||||
# Инициализировать узел (Установите имя вашего узла, например, daedalus)
|
||||
export NODE="daedalus"
|
||||
cd $REPO_DIR
|
||||
sudo -u adam ./init.sh
|
||||
```
|
||||
|
||||
**Специфичная для узла конфигурация**
|
||||
|
||||
Запустите скрипты инициализации с помощью диспетчера `root`:
|
||||
|
||||
```bash
|
||||
# Выполните последовательность для вашего конкретного узла (от имени пользователя 'adam')
|
||||
# Убедитесь, что вы выполнили 'source ~/.bashrc' или переподключились, если команда 'root' не найдена
|
||||
root configure base $NODE
|
||||
root configure ufw $NODE
|
||||
root configure crowdsec $NODE
|
||||
root configure cron $NODE
|
||||
```
|
||||
|
||||
### Хранение и усиление безопасности
|
||||
|
||||
Определите уровни данных (tiers) и защитите среду, создав непривилегированных пользователей для контейнеризированных сервисов.
|
||||
|
||||
```bash
|
||||
# Создать (или примонтировать) директории хранилища
|
||||
sudo mkdir -p /srv/my-infrastructure-root-$NODE-{tier1,tier2,tier3}
|
||||
|
||||
# Настроить уровни и непривилегированных пользователей
|
||||
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 %}}
|
||||
|
||||
---
|
||||
|
||||
**См. также:**
|
||||
|
||||
- [Doc: Docker - Install on Debian](https://docs.docker.com/engine/install/debian/)
|
||||
Reference in new issue
Block a user