Обновить docs/ansible/# 09. Ansible — общее описание репозитория ## 🎯 Цель репозитория Автоматизированное развертывание и обслуживание всех сервисов домашнего мультимедиа центра. Сервер стал полноценной частью семьи: дети смотрят мультфильмы, жена слушает ау01-overview.md

docs/ansible/# 09. Ansible — общее описание репозитория ## 🎯 Цель репозитория Автоматизированное развертывание и обслуживание всех сервисов домашнего мультимедиа центра. Сервер стал полноценной частью семьи: дети смотрят мультфильмы, жена слушает ау01-overview.md

@@ -0,0 +1,174 @@
+# 09. Ansible — общее описание репозитория
+
+## 🎯 Цель репозитория
+
+Автоматизированное развертывание и обслуживание всех сервисов домашнего мультимедиа центра.  
+Сервер стал полноценной частью семьи: дети смотрят мультфильмы, жена слушает аудиокниги, все общаются через голосовой чат или текстовые сообщения с друзьями.  
+Данный репозиторий создан для того, чтобы:
+
+- В случае непредвиденной ситуации кто-то из близких мог разобраться в конфигурации и продолжить поддержку сервера.
+- Я сам мог не помнить всех деталей настройки, которые делал несколько лет назад, и быстро находить нужную информацию.
+- Воспроизводить развертывание сервисов на новом оборудовании при необходимости.
+
+Вся конфигурация описана в виде кода (Infrastructure as Code) с использованием Ansible.
+
+---
+
+## 🖥️ Управляемые хосты
+
+Хосты представляют собой LXC-контейнеры в Proxmox, каждый отвечает за свою группу сервисов.  
+Файл инвентаря: `inventories/hosts`
+
+### Группы и хосты
+
+| Группа           | Хост      | IP-адрес    | Назначение                              |
+|------------------|-----------|-------------|-----------------------------------------|
+| `pve-server`     | proxmox   | 192.168.1.200 | Гипервизор Proxmox                     |
+| `gateway-server` | gateway   | 192.168.1.201 | Шлюз, VPN, роутинг                     |
+| `data-server`    | data      | 192.168.1.202 | Хранилище данных, Samba                 |
+| `media-server`   | media     | 192.168.1.203 | Медиасервисы (Jellyfin, Audiobookshelf)|
+| `photo-server`   | photo     | 192.168.1.204 | Фото (Immich)                          |
+| `talk-server`    | talk      | 192.168.1.206 | Коммуникации (Snikket, Mumble)         |
+| `games-server`   | games     | 192.168.1.207 | Игровые серверы (Minecraft)            |
+| `manage-server`  | manage    | 192.168.1.208 | Управление (Heimdall, NPM, Grafana)    |
+| `git-server`     | git       | 192.168.1.209 | GitLab                                 |
+| `ansible-server` | ansible   | 192.168.1.210 | Хост, с которого запускается Ansible   |
+| `torrent-server` | torrent   | 192.168.1.211 | Торренты (qBittorrent, TorrServer)     |
+
+Все хосты используют Python 3 как интерпретатор (`ansible_python_interpreter=/usr/bin/python3`).
+
+---
+
+## 🛠️ Технологии и подходы
+
+- **Ansible** — управление конфигурацией.
+- **Docker Compose** — все сервисы запускаются в контейнерах, конфигурация генерируется через шаблоны.
+- **Jinja2** — шаблонизация конфигурационных файлов (docker-compose.yml, конфиги сервисов).
+- **Handlers** — перезапуск сервисов только при изменении конфигурации.
+- **Групповые переменные** — единый файл `group_vars/all.yml` для общих настроек.
+- **Ansible Vault** — хранение секретов (пароли, токены) в `vault.yml`.
+- **Модульность** — каждая роль отвечает за один сервис или задачу.
+- **Идемпотентность** — повторный запуск плейбука не ломает существующую конфигурацию.
+
+---
+
+## 📂 Структура репозитория
+
+| Каталог / файл               | Описание                                                                               |
+|------------------------------|----------------------------------------------------------------------------------------|
+| `arhive_roles/`              | Роли, которые не используются активно (сохранены для истории)                          |
+| `group_vars/`                | Переменные для всех хостов (файл `all.yml`)                                           |
+| `inventories/`               | Файлы инвентаря (хосты, группы)                                                        |
+| `roles/`                     | Основные роли — каждый сервис или задача                                               |
+| `olimp-deploy.yml`           | Главный плейбук, включающий все роли                                                   |
+| `vault.yml`                  | Зашифрованный файл с секретами (редактируется через `ansible-vault`)                  |
+
+### Основные роли (`roles/`)
+
+| Роль                  | Назначение                                      |
+|-----------------------|-------------------------------------------------|
+| ampache               | Музыкальный стриминг-сервер                     |
+| audiobookshelf        | Сервер для аудиокниг и подкастов                |
+| base_setup            | Базовая настройка системы (обновление, пакеты)  |
+| bitwarden             | Менеджер паролей (Vaultwarden)                  |
+| bookstack             | Вики / база знаний                              |
+| cadvisor              | Мониторинг Docker-контейнеров                   |
+| calibre-web           | Веб-интерфейс для библиотеки Calibre            |
+| docker                | Установка Docker и Docker Compose               |
+| flibusta              | Зеркало библиотеки Флибуста (Z-Library)         |
+| gitlab                | GitLab CE                                       |
+| grafana               | Визуализация метрик (Grafana + VictoriaMetrics) |
+| heimdall              | Стартовая страница (дашборд)                    |
+| immich                | Фотогалерея / альтернатива Google Photos        |
+| jellyfin              | Медиасервер (видео, музыка)                     |
+| loki                  | Система сбора и хранения логов                  |
+| mealie                | Менеджер рецептов                               |
+| meshcentral           | Удалённое управление компьютерами               |
+| minecraft             | Игровой сервер Minecraft                        |
+| mumble                | Голосовой чат (Mumble)                          |
+| npm                   | Nginx Proxy Manager                             |
+| promtail              | Агент сбора логов для Loki                      |
+| proxmox_base_setup    | Базовая настройка хостов Proxmox                |
+| proxmox_monitoring    | Мониторинг Proxmox (pve_exporter)               |
+| qbittorrent           | Торрент-клиент                                  |
+| snikket               | Коммуникационный сервер (XMPP)                  |
+| system_cleanup        | Очистка системы (логи, временные файлы)         |
+| teamspeak             | Голосовой сервер TeamSpeak                      |
+| torrserver            | Торрент-стриминг (TorrServer)                   |
+
+### Архивные роли (`arhive_roles/`)
+
+| Роль                | Описание                                            |
+|---------------------|-----------------------------------------------------|
+| dashy               | Альтернативный дашборд (не используется)            |
+| [delete]pve_monitoring | Старая версия мониторинга Proxmox (удалена)       |
+| matrix              | Сервер Matrix (неактивен)                           |
+
+---
+
+## 📋 Требования к окружению
+
+Для работы с репозиторием необходимы:
+
+- **Ansible** (ядро): версия 2.18.10
+- **Коллекции**: установлена `community.docker` 4.8.1 (используется для управления Docker Compose)
+- **Python**: 3.12.3 на управляющем хосте
+- **Jinja2**: 3.1.2
+- **Доступ по SSH** ко всем хостам (настройки в `ansible.cfg` или через переменные)
+- **Docker и Docker Compose** установлены на целевых хостах (обеспечивается ролью `docker`)
+- **Ansible Vault** пароль для расшифровки `vault.yml` (должен быть доступен при запуске)
+
+**Установленные пакеты Python:**
+- `ansible` 11.11.0
+- `docker` 7.1.0
+
+**Команды для проверки:**
+```bash
+ansible --version
+# ansible [core 2.18.10]
+ansible-galaxy collection list | grep community.docker
+# community.docker 4.8.1
+pip list | grep -E "ansible|docker"
+# ansible 11.11.0
+# docker 7.1.0
+```
+
+---
+
+## 👨‍🏫 Для новичков: что такое Ansible?
+
+Если вы никогда раньше не работали с Ansible, вот краткое введение:
+
+- **Ansible** — это инструмент автоматизации. Вы описываете желаемое состояние системы в YAML-файлах, а Ansible приводит систему к этому состоянию.
+- **Плейбук** (playbook) — главный файл, который содержит список «пьес» (plays). Каждая пьеса выполняется на определённой группе хостов и включает набор задач (tasks).
+- **Роль** (role) — набор задач, переменных, шаблонов и обработчиков, объединённых для решения одной задачи (например, установка Jellyfin). Это помогает организовать код.
+- **Задача** (task) — конкретное действие: создать каталог, скопировать файл, запустить Docker-контейнер и т.д.
+- **Модуль** — встроенная функция Ansible (например, `docker_compose`, `copy`, `file`).
+- **Переменные** — хранят значения, которые могут меняться (пути, порты, имена пользователей). Определяются в `group_vars`, `host_vars`, внутри ролей или в плейбуке.
+- **Шаблон Jinja2** — файл с расширением `.j2`, в который подставляются переменные. Используется для генерации конфигов.
+- **Обработчик** (handler) — задача, которая выполняется только в том случае, если её уведомила другая задача (например, перезапуск сервиса после изменения конфига).
+- **Ansible Vault** — шифрование секретных данных (паролей, ключей) в YAML-файлах.
+
+**Базовые команды:**
+
+```bash
+# Проверка синтаксиса плейбука
+ansible-playbook olimp-deploy.yml --syntax-check
+
+# Запуск плейбука (с запросом пароля vault)
+ansible-playbook olimp-deploy.yml --ask-vault-pass
+
+# Запуск только определённой роли (тег)
+ansible-playbook olimp-deploy.yml --tags jellyfin
+
+# Проверка подключения ко всем хостам
+ansible all -i inventories/hosts -m ping
+```
+
+В следующих разделах документации каждый элемент будет разобран подробно, с примерами и пояснениями.
+
+---
+
+## 📝 Статус
+
+Документация актуальна на 23 марта 2026 года. По мере изменений в инфраструктуре разделы будут обновляться.